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Preface 



Purpose and Audience 



Design 



The purpose of the RT-11 Software Support Manual is to provide detailed 
descriptions of the software components of the RT-11 operating system. 

It is intended for programmers with experience in MACRO-11 assembly 
language who are interested in system-level programming, and for all ap- 
plication programmers who want to improve their technical understanding 
of the RT-11 operating system. (While the RT-11 Software Support 
Manual is not strictly a tutorial manual, it does provide valuable 
background information for application programmers.) 

This manual will be particularly useful to you if you are a system program- 
mer and your job is to support RT-11 for other users, you need to use 
devices that RT-11 does not already support, or you plan to alter the 
RT-11 software components. This manual can help you design more effi- 
cient programs if you are an apphcations programmer, especially if you plan 
to use the foreground/background, extended memory, or multi-terminal 
capabilities of RT-11. 

NOTE 

DIGITAL does not maintain software that you have 
changed in any way! Altering the RT-11 software com- 
ponents voids your warranty and terminates your 
maintenance service, so refrain from making changes un- 
less you have the technical expertise to be responsible for 
the system afterwards. 

Bef oreyou read this manual yc»u should be familiar with the topics covered 
in the RT-11 System User's Guide and with the programmed requests 
documented in the RT-11 Programmer's Reference Manual. The RT-11 
Software Support Manual contains information that can help you use 
system resources and the programmed requests more effectively. 

The resource that can best help you while you are using this manual — 
especially if you are interested in monitor internals — is the microfiche 
listing of the RT-11 commenttjd source files. 



This manual consists of ten chapters and three appendixes. The first two 
chapters provide an overview of the RT-11 system in general as well as in- 
formation on the components, their arrangement in memory, and their 
gross structure. The chapters that follow describe the previously introduc- 
ed system components in greater depth. 
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Chapter 1 provides an overview of the history of RT-ll's development. 

Chapter 2 describes how the software components are arranged in memory 
and shows how the arrangement changes dynamically. It also provides an 
overview of the components themselves. 

Chapter 3 describes the internals of the Resident Monitor that are generally 
common to the three RT-11 monitors. Topics that it covers include ter- 
minal service, timer service, I/O queuing, foreground/background considera- 
tions, system jobs, and data structures. 

Chapter 4 describes the internals of the Resident Monitor that are the basis 
of extended memory systems. It provides information on how the memory 
management hardware works, how RT-11 implements support for 124K 
words of memory, and how to design and code application programs. 

Chapter 5 covers a special feature of RT-11: the ability to use more than 
one terminal, or multi-terminal support. The chapter includes an example 
application program. 

Chapter 6 is an introduction to interrupt service in RT-11. It is useful to 
progranuners who need to add a device to their system configuration that is 
not already supported by RT-11. The chapter defines the structure and 
contents of an in-line interrupt service routine, and includes information for 
servicing interrupts in different RT-11 monitor environments. 

Chapter 7 is a logical continuation of Chapter 6. It explains the differences 
between in-line interrupt service routines and device handlers. It describes 
how to design, code, install, and debug a device handler. The chapter also 
covers some special features of handlers and gives considerations for 
handlers that will operate in various RT-11 monitor environments. Lastly, 
it lists requirements for system device handlers, and describes the 
bootstrap. 

Chapter 8 describes the structure and format of RT-11 files. It covers 
stream ASCII, LDA, REL, OBJ, STB, and SAV files, library files, error log- 
ging files, CREF files, and files with overlays. 

Chapter 9 provides information on device directories, file storage, and for- 
mats. It documents the structure of directories for random-access devices, 
and shows how to repair a directory that has been corrupted. It also 
describes the structure of magtapes and cassettes. 

Chapter 10 describes unique attributes of various physical devices and pro- 
vides information necessary for programming specifically for those devices. 

Appendix A provides commented listings of three RT-11 device handlers: 
RK, DX, and PC. 

Appendix B explains how to convert device handlers that were written for 
V03 or V03B of RT-11 to the current device handler format. 

Appendix C contains a listing of a sample appUcation program that uses in- 
line interrupt service to control an analog-to-digital converter in a typical 
laboratory situation. 
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Documentation Conventions 



The following symbolic and vc»cabulary conventions are used throughout 
this manual. Familiarize yourself with them before you continue reading. 

Memory refers to all kinds of physical storage in the computer itself; it in- 
cludes core and semiconductor memory. It is distinguished from storage on 
peripheral devices, such as disk or tape. 

In all diagrams of memory, the high addresses are at the top of the picture 
and the bottom of the figure rcipresents address 0. In descriptions of data 
structures and tables, low addresses and offsets are at the top of each table. 

In discussions of extended memory systems, low memory refers to memory 
belov/^ the 28K-word boundary. However, for LSI computers with the 
MSVll-DD memory board and a special jumper installed, low memory con- 
sists of the memory locations below the 30K-word boundary. 

The following acronyms are used throughout this manual: 
Name Meaning 



USR 


User Service Routine 


RMON 


Resident Monitor 


KMON 


Keyboard Monitor 


FB 


Foreground/Background 


XM 


Extended Memory 


SJ 


Single-Job 


BL 


Baseline 


EOT 


End-of-tape 


EOF 


End-of-file 


LEOT 


Logical end-of-tape 


EOT 


• Beginning-of-tape 


csw 


Channel Status Word 


PS 


Processor Status word! 



For your convenience, the following table shows the octal mask used to set, 
clear, or test each bit in a 16-bit word. 



Bit 


Octal Mask 





1 


1 


2 


2 


4 


3 


10 


4 


20 


5 


40 


6 


100 


7 


200 


8 


400 


9 


1000 


10 


2000 


11 


4000 


12 


10000 


13 


20000 


14 


40000 


15 


100000 
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Chapter 1 
Historical Overview 



At its conception in 1972, RT-11 was designed to be a small, fast, easy-to- 
use operating system for the PDP-11 family of minicomputers. It was 
developed as a single-user syst;em for real-time and computational use; its 
target applications were data acquisition, process control, and, of course, 
program development. 

The following sections provide an overiew of the history of RT-11 's 
development, showing how the operating system has evolved over the 
course of eight years and four major releases. For a comprehensive over- 
view of the hardware, software, and documentation components of today's 
RT-11 operating system, see Chapter 1 of the RT-11 System User's Guide. 

The year 1971 was an exciting time for the computer industry. The PDP-1 1 
computer was only a year old and DIGITAL was making computing power 
feasible for thousands of applications with the introduction of this relative- 
ly inexpensive 16-bit minicomputer. ^ 

The software then available for the PDP-11 consisted of PTS (Paper Tape 
Software, which included the PAL- 1 IS Assembler) and DOS- 11 (a batch- 
oriented system). Clearly, the situation called for a low-cost, interactive 
system that could be used for real-time and computational applications, and 
for program development. 

A popular operating system for the PDP-8, called OS/8, was the design 
model for the new PDP-11 operating system, tentatively called OS-11. The 
new operating system was designed to be a small, single-user, interactive 
system with event-driven real-time I/O, that would run on PDP-11 com- 
puters with 28K words of memory or less. It was designed to have a simple, 
modular structure; device handlers would be used for I/O transfers so ap- 
plication programming could be device-independent, and files would be 
stored in contiguous blocks on disk so record management would not be a 
programming concern. 



1.1 Version 1 



Actual development work on OS-ll began in the fall of 1972. A group of 
five system programmers and one technical writer set about refining the 
design for OS-11 and producing the software and the manual. The ground- 
work was laid to make OS-11 compatible with OS/8 and TOPS-10. 

The first version of OS-11 inchided the single-job monitor and a set of pro- 
gram development tools: EDIT, MACRO-11, LINK, ODT, PIP, PATCH, 
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EXPAND and ASEMBL (tools for developing macros in 8K-word systems), 
and PIPC (for cassettes). BASIC-11, the first product to require RT-11 as 
its base system, was also part of Version 1. The single-job monitor provided 
necessary services to running programs and supervised the queued I/O 
system. The operating system supported seven devices: RK, LP, TT, CT, 
PR, PP, and DT. 

OS-11 was renamed first to RTPS-11 (Real-Time Programming System), 
then to RT-11 (Real Time). Version 1 of RT-11 was completed in the fall of 
1973, and support for the GT40 video display was added in early 1974. 



1.2 Version 2 



It soon became apparent that RT-11 was successful. More system pro- 
grammers and technical writers were added to the group, and development 
for another release was begun. Versions 2, 2B, and 2C brought some signifi- 
cant new features to the operating system, A new monitor was developed 
that permitted two jobs to run in a foreground/background environment. 
Support was added for new peripheral devices, including MM, MT, CR, DP, 
RF, DX, and DS. A number of utility programs were added to improve the 
set of program development tools. These included CREF, LIBR, PATCHO, 
DUMP, FILEX, SRCCOM, and BATCH. FORTRAN IV was released with 
Version 2, and the operating system software included a Ubrary of 
FORTRAN-callable subroutines, called SYSLIB. Version 2 was completed 
in the faU of 1974; the 2C update was released in early 1976. 



1.3 Version 3 



Version 3 of RT-11 was another major release. Most significant was the 
development of the extended memory monitor from a conditional assembly 
of the foreground/background monitor source files. This permitted RT-11 
to support systems with up to 124K words of physical memory. Products 
such as FORTRAN IV, CTS-300, and Multi-User BASIC-11 took advan- 
tage of this feature in ways that were transparent to appKcation programs. 
Support was included for multi-terminal systems as well, and device error 
logging was implemented. DCL (DIGITAL Command Language) was 
developed so that almost all system programs could be accessed by 
English-like monitor commands. Indirect files provided an easy-to-use alter- 
native to BATCH. 

Again, support was added for new DIGITAL peripheral devices; DL, DM, 
DY, NL, and PC (which replaced PR and PP). And, more system utility pro- 
grams were introduced: PIP was divided into PIP, DUP, and DIR. Other 
new utilities included PAT, FORMAT, and RESORC. System generation 
was designed to permit customization and provide system flexibility. The 
TECO editor was included in the distribution kits for the first time. Version 
3 was completed in the fall of 1977, and the 3B update was made available 
in early 1978. 
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1.4 Version 4 



"Things are more like they are now than they ever were before. " 

With Version 4, RT-11 could be called a mature product. The specific goals 
of this development effort were to make RT-11 easier to install and 
maintain. Tools were provided, in the form of BINCOM, SIPP, SRCCOM, 
and SLP, to make the genei-ation and installation of patches almost 
automatic. System jobs (special foreground jobs provided by DIGITAL) 
handled error logging and file queuing. Monitor files were separated from 
system device handler files, providing greater flexibiUty while saving 
storage space. Not least among the accomplishments was a change to the 
linker that permitted overlays t;o reside in extended memory rather than on 
a mass storage device. The KEJD and K52 Keypad Editors were included in 
the distribution kits. 

Version 4 was completed in <}arly 1980. By then there were well over 
seventeen thousand RT-11 systems installed around the world, making 
this operating system a successful venture indeed. 
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Chapter 2 

System Components and Memory Layouts 



This chapter introduces the components of the RT-11 system that can be 
memory resident. It provides maps of physical memory that show where 
the components are located, and it indicates how their positions can change 
dynamically. The components this chapter covers are divided into two 
groups: static components, which have a relatively fixed position in 
memory, and dynamic components, whose locations are changeable. 

The components are arranged t;o leave the most space available for user pro- 
grams and to be flexible. Flexibility is obtained by positioning the com- 
ponents after determining the total amount of memory at bootstrap time. 
Normally, you do not have to take any special steps to move RT-11 from 
one PDP-11 computer to another. 



2.1 Static Components 



The static components have fixed locations in memory. Their actual ad- 
dresses vary from one PDP-11 computer to the next, depending on how 
much memory each computer has available. The static components or areas 
are as follows: 

Trap vectors 

System communication area 

Interrupt vectors 

I/O page 

System device handler 

Resident Monitor 

Background job 



2.1.1 Trap Vectors 

Table 2-1 shows the memory locations from to 36, an area that contains 
the trap vectors. A plus sign ( + ) marks the locations that are reserved for 
use by RT-11. You should not attempt to modify these locations; a bitmap 
protects them each time you load a program. An asterisk (*) marks the loca- 
tions that your programs can use. Figure 2-1 is a summary of the trap vec- 
tor area information. 
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Table 21: Trap Vectors 

Location 



Contents 



0,2 + Monitor restart, executes the .EXIT request and returns control to the 

monitor (has additional uses in XM systems). 

4,6 + Odd address and bus time-out trap; RT-11 sets this to point to its inter- 

nal trap handler. 

10,12 + Reserved instruction trap; RT-11 sets this to point to its internal trap 

handler. 

14,16* BPT (breakpoint trap), T-bit trap (used by debugging utility programs). 

20,22* lOT, input/output trap. 

24,26* Powerfail and restart trap. Your programs can use this location unless 

you included support for powerfail restart through system generation. If 
your system includes the powerfail restart feature, locations 24 and 26 
are reserved for use by RT-11. 

30,32 + EMT, emulator trap; RT-11 uses this for programmed requests. 

34,36* TRAP instruction. Note that you cannot use the TRAP instruction in 

assembly language subroutines linked with FORTRAN IV, BASIC-11, 
or MU BASIC-11 programs; these languages use the TRAP instruction 
for internal error reporting. 



Figure 2-1: Trap Vector Area 
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2.1.2 System Communication Area 

The memory locations from 40 through 57 are called the system com- 
munication area. This area holds information about the program currently 
executing, as well as certain information normally used only by the monitor. 

The diagram in Figure 2-2 is a summary of the system communication area 
information. Table 2-2 describes the contents of each location. 

Figure 2-2: System Communication Area 
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Table 2-2: System Communication Area 

Location Contents 



40,41 Start address of job. When you link a file to create an RT-11 executable 
image, the linker sets the word at address 40 in the program's file to the 
starting address of tlie program. This word is loaded into memory loca- 
tion 40 at run time. When a foreground job executes, the FRUN proc- 
essor relocates this word to contain the actual starting address of the 
program. 

42,43 Initial value of stack pointer. If the user program does not set this value 
with an .ASECT directive, the value defaults to 1000 or to the top of the 
program's absolute s(5ction, whichever is larger. If a foreground p-Dgram 
does not specify a stack pointer in this word (by using an .ASECT direc- 
tive), the FRUN processor allocates a default stack of 128 decimal bytes 
immediately below the program, and the initial stack pointer value is 
1000. You can use the linker /B:n option to set the initial value of the 
background job's stack pointer. 
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Table 2-2: System Communication Area (Cont.) 
Location Contents 



44,45 Job Status Word (JSW). This is a flag word for the monitor. The monitor 
mfdntains some of the bits itself, and your program can set or clear 
others. See Section 2.1.2.2 for more information on the JSW. 

46,47 USR load address. This word is normally 0, but you can set it in the file 
or at run time to any valid word address in your program. If this word is 
0, the USR loads in its default location through an address contained in 
offset 266 of RMON. If this word is not 0, the USR simply loads at the 
address it specifies, unless the USR is set NOSWAP. This location is 
cleared by an exit to KMON (via .EXIT, CTRL/C, or fatal error). 

50,51 High memory address. In this word the monitor maintains the highest 
address your program can use. The linker sets this word initially to the 
high-limit value. You can modify it by using the .SETTOP programmed 
request. Your program must never modify this word directly. In XM 
systems, locations 50 and 51 in the file contain the address that is the 
top of the root section plus the low memory {10) overlays. In memory, 
locations 50 and 51 contain the same value unless the program issues a 
.SETTOP. In this case, these locations contain the highest available vir- 
tual address (see Section 4.4.4,6). 

52 EMT error code. If a monitor request results in an error, the code 
number of the error is always returned in byte 52 in memory and the 
carry bit is set. Each monitor call has its own set of possible errors. Byte 
52 in the job's file has a different meaning (see Chapter 8). 



NOTE 

Always address location 52 as a byte, never as a word, since 
byte 53 has a separate function. 

53 User program error code (USERRB). If a user program encounters errors 
during execution, it indicates the error by using this byte in memory. See 
Section 2.1.2.1 for more information about this byte. See Chapter 8 for 
its meaning in the job's file. 

54,55 Address of the begining of the Resident Monitor. RT-11 always loads 
the monitor into the highest available memory locations of low (rather 
than extended) memory; this word in memory points to its first location. 
Never alter this word — doing so causes RT-11 to malfunction. See 
Chapter 8 for the meaning of this word in the job's file. 

56 Fill character (seven-bit ASCII). Some high-speed terminals require fill 
(nuU) characters after printing certain characters. Byte 56 in memory 
should contain the ASCII seven-bit representation of the character after 
which fills are required. See Chapter 8 for the meaning of this bit in the 
job's file. 

57 Fill count. This byte in memory specifies the number of fill characters 
that are required. The number of characters is determined by hardware. 
If bytes 57 and 56 are 0, no fill is required. See Chapter 8 for the meaning 
of this byte in the job's file. For more information on the terminals that 
require fill characters, see the RT-11 Installation and System Genera- 
tion Guide. 
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2.1.2.1 User Error Byte — The Keyboard Monitor examines the user error 
byte when a program terminEites. If your program has reported a signifi- 
cant error in this byte, KMON can abort any indirect command files in use. 
This prevents spurious results from occurring if subsequent commands in 
the indirect file depend on the successful completion of all prior commands. 

A program can exit in one of the following states: 

• Success 

• Warning 

• Error 

• Severe error 

• Unconditionally fatal error 

The program status is success when the execution of the program is free of 
errors. 

The warning status indicates that warning messages occurred, but the pro- 
gram ran to completion. 

The error status indicates that a user error occurred and the program did 
not run to completion. This level is also used by RT-11 system programs 
when they produce an output file even though it may contain errors. For ex- 
ample, a compiler can use the error level to indicate that an object file was 
produced, but the source program contains errors. Under these conditions, 
execution of the object file will not be successful if the module containing 
the error is encountered. 

The severe status indicates that the program did not produce any usable 
output, and any command or operation depending upon this program out- 
put will not execute properly. This type of error can result when a resource 
needed by the program to complete execution is not available — for exam- 
ple, insufficient memory space to assemble or compile an appUcation 
program. 

The unconditionally fatal status indicates that not only has an operation 
completely failed, but that the integrity of the monitor itself is 
questionable. 

Utility programs and the Keyboard Monitor always set the user error byte 
to reflect the result of each monitor command you issue. Normally, indirect 
command files abort when there has been a monitor command error. By set- 
ting the error level to unconditionally fatal with the SET ERROR NONE 
command, you guarantee that indirect command files will continue to ex- 
ecute despite individual monitor command errors. Only unconditionally 
fatal errors that indicate problems within the Keyboard Monitor itself abort 
indirect files at the SET ERROR NONE level. Table 2-3 shows the bits of 
byte 53, their status, and the status code printed by the RT-11 system util- 
ity program messages. 
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Table 2-3: User Error Byte 
Bit Mask Status 



RT-11 Message 



1 Success ?prog-I-text, or none 

1 2 Warning ?prog-W-text 

2 4 Error ?prog-E-text 

3 10 Severe ?prog-F-text 

4 20 Fatal ?prog-U-text 



Bits 5 through 7 of the user error byte are reserved for DIGITAL'S future 
use; do not use them in your programs. Programs should never clear byte 
53, and should set it only through a BISB instruction, as the following ex- 
ample shows. If more than one bit is set at any given time, the highest bit is 
the one that RT-11 recognizes. 



USERRB =53 




SUCCS$ =1 




WARN$ =2 




ERRORS =4 




SEVERS =10 




U FAILS =20 




ERROR: BISB #ERROR$,@#USERRB 


;SET ERROR STATUS 


CLR RO 


;HARD EXIT 


.EXIT 





Note that this byte is meaningful only for the Keyboard Monitor and for 
background jobs. This is because it was designed to be used by system util- 
ity programs and language processors, which run as background jobs. A 
foreground job can set it, but that action has no effect on the system. 

2.1.2.2. Job Status Word (JSW) — Bytes 44 and 45 make up the Job Status 
Word, or JSW. Table 2-4 shows the meanings of the bits in this word. The 
bits marked with an asterisk (*) can be set by a user program during execu- 
tion. Bits marked with a plus sign ( -I- ) are set at load time. Note that some 
bits can be set at both load and run time. Unused bits are reserved for 
future use by DIGITAL. Figure 2-3 shows a summary of the JSW. 



Table 2-4: Job Status Word (JSW) 

Bit 
Number 



Meaning When Set 



15 USR swap bit (SJ only). The monitor sets this bit when a program does 

not require the USR to swap. (See Section 2.2.3 for details on the USR.) 
Your program must not alter this bit. 

14 + * Lower-case bit. Disables automatic conversion of typed lower-case to 

upper-case characters. EDIT sets it when you type the EL command. 
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Table 2-4: Job Status Word (JSW) (Cont.) 

Bit 
Number Meaning When Set 



13 + * Reenter bit. Indicates that a program can be restarted from the terminal 

when you type the REENTER command. 

12 + * Special mode terminal bit. Indicates that the job is in a special keyboard 

mode of input. Refer to the explanation of the .TTYIN and .TTINR pro- 
grammed requests in the RT-11 Programmer's Reference Manual for 
details. 

11 + * Pass line to KMON bit. Indicates, when a program exits, that the pro- 

gram is passing a command line to KMON. This action causes any open 
indirect file to abort. The command line should be stored in the CHAIN 
information area, locations 500 through 776. Refer to the example pro- 
gram for .EXIT in the RT-11 Programmer's Reference Manual. This bit 
is not available to foreground or system jobs under the FB and XM 
monitors. 

10 -I- Virtual image bit (XM only). Indicates that the job to be loaded is a vir- 

tual job. You must set this bit yourself in the executable file before you 
attempt to run the program. Do this at assembly time by using an 
.ASECT directive and modifying the JSW, or before run time by patch- 
ing this location in the file. See Chapter 4 for more information on virtual 
jobs. 
9 Overlay bit. This bit is set by the linker if the user program uses the 

linker overlay feature. 

8 -I- CHAIN bit. This bit can be used in two ways. If it is set in a job's save 

image, the monitor loads words 500 through 776 from the save file when 
the job is started, even if the job is entered with .CHAIN. (These words 
are normally used to pass parameters from one job to another across a 
.CHAIN.) 

The monitor sets this bit when the job is running if and only if the job 
was actually entered with a .CHAIN. 

7 -(- * Error halt bit (SJ only). Indicates that the system should halt when an 

I/O error occurs. If you want the system to halt when a device I/O error 
occurs, you should set this bit. 

6 -)- * Inhibit terminal wait bit (FB and XM only). Inhibits the job from enter- 

ing a console terminal wait state. For more information, refer to the sec- 
tions concerning .TTYIN, .TTINR, .TTYOUT and .TTOUTR in the 
RT-11 Programmer's Reference Manual. 

4-5 Reserved. 

3 -(- * Nonterminating .GTLIN bit. When bit 3 of the JSW is set and your 

program encounters a CTRL/C in an indirect command file, the .GTLIN 
request collects subsequent lines from the terminal. If you then clear bit 3 
of the JSW, the next line collected by the .GTLIN request is the CTRL/C 
in the indirect command file; this causes the program to terminate. Fur- 
ther input will com*; from the indirect command file, if there are any more 
lines in it. The LINK, DUP, SIPP, SLP, QUEMAN, SRCCOM, and LIBR 
utilities make use of this feature. To activate it in an indirect file, put an 
uparrow (') followed by a C on a line by itself in the file. This causes the 
utilities to accept the response from the terminal instead of taking it 
directly from the file. 

The following indirect file shows how to obtain a response from the termi- 
nal: 



System Components and Memory Layouts 2-7 

March 1981 



Table 2-4: Job Status Word (JSW) (Cont.) 

Meaning When Set 



Bit 
Number 



0-2 



RUN LINK 

TEST,TEST=M0D1,UB/I 

"C 

All further input to the linker will come from the terminal, as a result of 
the "C in the indirect command file. 

Reserved. 



Figure 2-3: Job Status Word (JSW) Summary 
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BITSMARKEDWITH AN ASTERISK C) ARE BITS THAT YOU CAN SET DURING EXECUTION. 
BITS MARKED WITH A PLUS SIGN 1+) CAN BE SET AT LOAD TIME. 

2.1.3 Interrupt Vectors 

Table 2-5 shows the locations in the low memory area that are reserved for 
interrupt vectors. Figure 2-4 shows how the interrupt vector area relates to 
the rest of memory. 



Table 2-5: Interrupt Vectors 
Location 



Contents 



60,62 DLll: Console terminal input 

64,66 DLll: Console terminal output 

70,72 PCll: Paper tape reader 

74,76 PCll: Paper tape punch 

100,102 KWll-L: Line clock 

104,106 KWll-P: Programmable clock 

110,112 Reserved ' 

114,116 Memory system errors: parity, cache, and uncorrectable ECC errors 

120,122 XYll: X/Y Plotter ' 

124,126 DRll-B: DMA interface^ 

' This vector is used by RSTS/E. Take this into consideration if you run both RT-11 and 
RSTS/E on the same PDP-11. 
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Table 2-5: Interrupt Vectors (Cont.) 

Location Contents 

130,132 ADOl: Analog to digital subsystem ' 

134,136 AFCll: Analog input subsystem '^ 

140,142 AAll: Digital to einalog subsystem ' 

144,146 AAll: (requires tvi^o vectors) ^ 

160,152 Reserved 

164,156 Reserved 

160,162 RLll/RLVll: RL()1/RL02 Disk cartridge 

164,166 Reserved 

170,172 LP/LS/LVll Line printer #1 " 

174,176 LP/LS/LVll Line printer #2 ^ 

200,202 LP/LS/LVll Line printer #0 (includes LA180 parallel interface) 

204,206 RH11,RH70: RS03/RS04 Fixed-head disk; 

RFll: Fixed-head disk 

210,212 RK611/RK711: RK06/RK07 Disk cartridge 

214,216 TCll: DECtape 

220,222 RKll/RKVll: RK05 Disk cartridge 

224,226 RH11/RH70: TU16, TE16, TU45 Magtape; 

TMll: TUIO/TEIO Magtape; 
TS03: Magtape 
TSll: Magtape first controller (others float) 

230,232 CDll/CMll/CRll; Card reader 

234,236 UDCll: Digital control subsystem ^ 

240,242 PIRQ, (programmed interrupt request) ' 

244,246 FPP or FIS floating-point exception 

250,252 KTll: Memory management fault 

254,256 RPll: RP02/03 Disk; 

RH11/RH70: RP04/05/06/RM02/03 Disk 

260, 262 TAl 1 : Cassette tape 

264,266 RX11/RXV11/RX211/RX2V1: RXOl RX02 Diskette 

;J70,272 LP/LS/LVll Line printer #3 » 

1274,276 LP/LS/LVll Line printer #4 ' 

!J00,302 Start of the floating vector area 

320,322 VT11/VS60 Graphics terminal (requires three vectors) 

iJ24,326 VT11/VS60 

330,332 VT11/VS60 

This vector is assigned to a hardware device that is optional in RT-11. If your configura- 
tion includes this device, use this vector for it. 

This vector is assigned to hardware that is not supported by RT-11. 
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Figure 2-4: Interrupt Vector Area 
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2.1.4 I/O Page 

The highest 4K words of addressing space in PDP-11 computers are reserv- 
ed for device control, status, and data buffer registers. This area is called 
the I/O page. In addition to the device registers, it also contains the Pro- 
cessor Status word (except on the PDP-11/03), and, for some processors, 
the system's general registers (RO through R5), the stack pointer (R6), and 
the program counter (R7). Locations in the I/O page are directly ad- 
dressable by application programs and system software, but since they are 
bus addresses and not memory locations, they cannot be used to store code 
and data. Figure 2-5 shows where the I/O page is addressed in relation to 
the rest of the system components. You can find more information on the 
I/O page and the device registers for your own processor and peripherals in 
the PDP-11 Processor Handbook, the PDP-11 Peripherals Handbook, the 
Microcomputer Processor Handbook, the Memories and Peripherals Hand- 
book, and in most hardware manuals. 



2-10 System Components and Memory Layouts 



Figure 2-5: I/O Page 
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2.1 .S System Device Handler 

The system device handler is the handler for the device from which the 
system was bootstrapped. Chapter 7 describes the structure of a system 
device handler in detail. 

At bootstrap time, the monitor is linked together with the system device 
handler file found on the system volume. The system device handler is 
loaded into memory first, immediately below the I/O page. The Resident 
Monitor is loaded below the system device handler. Once it is read into 
memory, the system device handler remains resident and does not change 
its location. Figure 2-6 shows where the system device handler resides in 
memory. 
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Figure 2-6: System Device Handler 
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2.1 .6 Resident Monitor (RMON) 

The Resident Monitor (RMON) is the RT-11 monitor component that is 
always resident in memory. When you bootstrap an RT-11 system, the 
bootstrap routine determines how much main memory is available. RMON 
loads at the highest possible low memory address, just below the system 
device handler. It does not move during system operation. 

RMON contains routines to handle the programmed requests in RT-11. It 
also contains the background job's impure area in FB and XM systems, the 
error processor, timer routines, console terminal service routines, USR 
swap routines, and other monitor functions. Figure 2-7 shows a summary 
of the contents of the Resident Monitor. In the figure, components marked 
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with an asterisk (*) are not pairt of the SJ Resident Monitor. See Chapter 3 
for more information on the Resident Monitor. 

Link maps of the distributed RT-11 monitors (base-line, single-job, and 
foreground/background) are part of the distribution kit. They exist as files 
named RTBL.MAP, RTSJ.MAP, and RTFB.MAP. Listings of the maps 
also appear in Appendix G of the RT-11 Installation and System Genera- 
tion Guide. Table 2-6 Usts the p-sects that make up the Resident and 
Keyboard Monitors. 

Figuire 2-7: Resident Monitor (RMON) 
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Table 2-6: Monitor P-sects 
P-sect Name 



Contents 



RTll Keyboard Monitor 

RMNUSR USR buffer and code 

RTDATA Resident Monitor fixed offsets and database 

OWNERS $OWNER table 

UNAM1$ $UNAM1 table 
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Table 2-6: Monitor P-sects (Cont.) 

P-sect Name Contents 



UNAM2$ $UNAM2 table 

PNAME$ $PNAME table 

ENTRY$ SENTRY table 

STAT$ $STAT table 

DVREC$ $DVREC table 

MTTYS Multi-terminal terminal control blocks 

RMON Resident Monitor 

XMSUBS Extended Memory routines 

MTEMT$ Multi- terminal programmed requests 

MTINTS Multi-terminal interrupt service 

STACKS Resident Monitor stacks (not in SJ) 

PATCHS Patch space 

OVLYnn Keyboard Monitor overlays containing command processors 



2.1.7 Background Job 

The user job in an SJ system and the background job in an FB system are 
essentially identical for the purpose of this discussion. The RT-11 utility 
programs, such as PIP, DUP, and DIR, run as user jobs. In FB systems, 
they run as background jobs. Figure 2-8 shows the general structure of a 
background job, as well as its relative location in memory. 

As you can see from Figure 2-8, the background job usually begins loading 
into memory at location 1000, and loads up to its high limit. There are three 
ways in which RT-11 can load a background job: RUN, R, and .CHAIN. 
They are described in the following three sections. 

2.1.7.1 RUN Command — One way to load a job (if it is not a virtual job) is to 
use the keyboard monitor RUN command. The RUN command is the same 
as the GET and START commands combined. First, if the SAV file is not 
on the system device, RUN (or GET) loads the handler for the proper 
device. When this occurs the Keyboard Monitor and the USR, which nor- 
mally occupy the space above the background job and below RMON, 
relocate themselves, if necessary. For more information on the USR and the 
Keyboard Monitor, see later sections of this chapter. 

The space available for background job loading consists of the background 
job area, the space occupied by KMON, and the space occupied by the USR 
(unless the USR is set to NOSWAP), If the job needs more space than these 
three areas, an error message prints and then control returns to the 
Keyboard Monitor. 
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Figure 2-8: Background Job 
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Once the job passes the size tests, RUN loads memory locations through 
476 from the file, if they are not protected. To check for protection, RUN 
looks at the bitmap in RMON,, and does not load any locations that are pro- 
tected either by RMON or by another job. 

Next, RUN loads all the memory locations from 500 through 776 from the 
file. This area is the default stack for the background job. 

To load locations 1000 and up, RUN examines the core control block, called 
the CCB, which starts at location 360 in the job file. The CCB is a bitmap 
created by the linker in which each bit represents one block in the file. When 
the linker takes data out of the OBJ file to go into the SAV file, it sets the 
CCB bit for each block of the SAV file that actually contains code or data. 
For example, if you Unk a file with a base address of 2000, the locations in 
your file from 1000 through 1776 do not contain data, and therefore the 
linker does not set the corresiponding bit in the CCB. RUN loads blocks 
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from the file into memory only if the corresponding CCB bits for them 
are set. 

If a block fits in memory in the area below KM ON that is reserved for the 
background job, RUN loads it directly. If a block would overlay either 
KMON or the USR, RUN copies the block out to the disk file SWAP.SYS. 
This process continues until the entire file is loaded into memory, or into 
memory plus SWAP.SYS. SWAP.SYS is just large enough to hold the 
amount of program code that would overlay the KMON and the USR. 

Finally, RUN (or START) jumps to RMON. If SWAP.SYS is in use, RMON 
reads its contents into memory, overlaying KMON and possibly the USR as 
well. Then RMON starts the program's execution. Figure 2-9 summarizes 
how the RUN command loads a job image into memory. 

When the program terminates, RMON reads KMON and the USR back into 
memory from the monitor .SYS file. The memory area up to the bottom of 
KMON contains the background job image. If the job overlaid KMON, the 
remainder of the job image is written out to SWAP.SYS. This procedure 
allows the Examine and Deposit commands to operate on the job image on 
disk, even though KMON has written over the job's locations in memory, 
and the RESTART command can restart the program. 

2.1.7.2 R Command — The R command is similar to the RUN command. 
One initial difference, however, is that the file to be loaded must reside on 
the system device (SY:). The reason for this restriction is that the R com- 
mand is not capable of loading another device handler in order to read the file. 

The R command loads memory locations through 776 the same way the 
RUN command does. It has a different procedure for loading locations 1000 
and up. The R command ignores the core control block in the file and it sets 
up parameters for RMON. RMON loads the rest of the file (up to its high 
limit; it does not load overlays) even if it overlays KMON and the USR. It 
ignores the file SWAP.SYS. Figure 2-10 summarizes how the R command 
loads a job image into memory. 

If the job is a virtual job, the monitor creates for the job a virtual memory 
partition, a static window and static region definition block, and then sets 
up the user mapping registers. At this point it starts the job's execution. 
(See Chapter 4 for more information on virtual jobs.) 

As with the RUN command, jobs (excluding virtual jobs) loaded with R use 
the SWAP.SYS file, if necessary, at program termination so that the Ex- 
amine and Deposit commands function correctly. Note that if a job issues a 
.SETTOP request to lower its high Umit before it exits, it may prevent the 
monitor from writing SWAP.SYS. 

2.1.7.3 .CHAIN Request — The third way to load a job is to chain to it from 
another job. The first job issues the .CHAIN programmed request to do 
this. The second job can use information in memory locations 500 through 
776 that was placed there by the first job. Consequently, the only difference 
between loading a job wth the RUN command and starting a job by chain- 
ing to it is that chaining does not load memory locations 500 through 776 
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from the second file unless you set the chain bit in the JSW of the second 
file at assembly time. 



Figure 2-9: RUN Command 
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Note that in XM systems, a virtual job cannot pass information when 
chaining to another job. In addition, you cannot chain to a virtual job. (See 
Chapter 4 for more information on virtual jobs.) Note also that chaining to 
a FORTRAN job does not preserve channel information from the previous 
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job. This is because FORTRAN itself closes the channels and discards the 
impure area. 



Figure 2-10: R Command 
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2.2 Dynamic Components 



Dynamic components do not always load into fixed places in memory. Once 
loaded, some of them can continue to shift location based on the state of the 
rest of the system. The dynamic components and areas are as follows: 

• Device handlers (device drivers) and free space 

• Foreground and system jobs 

• User Service Routine 

• Keyboard Monitor 
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As you read about the rest of the dynamic components, you will also learn 
how the system manages free space in memory. You have already seen how 
the system device handler and the Resident Monitor load at the highest 
possible addresses, and how the background job begins loading at location 
1000 and up. The strategy behind the way the system manages free 
memiory is that it attempts to make the most space available for foreground 
and background apphcation jobs. 

2.2.1 Device Handlers and Free Space 

Device handlers (drivers) are routines that provide the interface to the com- 
puter's hardware devices. The handlers drive, or service, peripheral devices 
and take care of moving datsi between memory and devices. Chapter 7 
describes device handlers in greater detail. 

RT-11 uses a dynamic scheme to provide memory space for loaded 
handlers, foreground jobs, system jobs, indirect file and command line ex- 
pansion, and the display text scroller. Memory is allocated in the region 
above the KMON/USR section and below RMON. If there is not enough 
memory in this region (initially, after the system is bootstrapped, there is 
none), memory is taken from the background region by "sliding down" the 
KMON and USR the required number of words. 

When memory allocated in this manner is released, the memory area is 
returned to a singly-Unked free memory list, the head of which is located in 
RMON. Any contiguous blocks are concatenated into a single larger block. 
A block found to be contiguous with the KMON/USR is reclaimed by 
"sliding up" the KMON/USR, thus removing the block from the list. 

Figure 2-11 shows an SJ system with a small application job and two load- 
ed device handlers. When you issue the LOAD monitor command the 
handler loads into the memory area just above the USR and KMON. The 
USR and KMON slide down in memory to provide the handlers with 
enough space, leaving less space for the user program. The GT ON com- 
mand is similar to the LOAD command, except that it specifically loads the 
VT11/VS60 video display handler. The GT handler is located in a Keyboard 
Monitor overlay instead of a .SYS file on a storage volume. Except for the 
fact that it is not stored as a separate handler file on a mass storage device, 
it functions the same as other liandlers. 

Once handlers are brought into memory, they do not move up or down, as 
the USR and KMON do. Figure 2-12 shows the system after the monitor 
UNLOAD command has removed one handler from memory. In the figure, 
the free space above handler #2 has not been reclaimed and is available for 
later use. A handler that is the same size as the empty space, or smaller, can 
be loaded there without causing any other components to move. 

Figure 2-13 shows the system after the second handler was unloaded. This 
time there is free space directly above the USR (the space formerly occupied 
by the two handlers), so the USR and KMON sUde up into it, making more 
space available for the user program. The GT OFF command is similar to 
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the UNLOAD command, except that it specifically unloads the VT11/VS60 
video display handler. 

Figure 2-11: SJ System with Two Loaded Handlers 
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2.2.2 Foreground and System Jobs 

In an FB or XM system, foreground jobs and system jobs are essentially 
identical. A system job is simply a special kind of foreground job that 
DIGITAL provides for you. The two RT-11 system jobs in the FB and XM 
environments are the error logger (EL) and the file queuing program 
(QUEUE). Figure 2-14 shows the general structure of a foreground job, as 
well as its relative location in memory. Handlers loaded after the fore- 
ground job are placed below it in memory, and above the USR. (See Chapter 
3 for more information on foreground and system jobs.) 
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Figure 2-12: SJ System with One Handler Unloaded 
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2.2.2.1 Difference Between Foreground and Background Jobs — There are some 
significant differences between foreground and background jobs. 

1. The impure area (described in Chapter 3) for the foreground job is 
located immediately below the job area itself. For background job, the 
impure area is always in the Resident Monitor, 

2. Another major difference is that a foreground job cannot dynamically 
change its memory allocation: the job is a fixed size. You can only 
change the size at FRUN time by using the /BUFFER:n option to in- 
crease the memory allocation. (Note that this option is ignored in XM 
systems for virtual .SAV files started with the FRUN or SRUN com- 
mand.) 
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3. You must load all the handlers a foreground job needs before the job 
attempts to use them. A background job, on the other hand, can use 
the .FETCH programmed request to load a handler when it is needed. 

4. For FB systems only, if the USR is swapped out and the foreground 
job needs it, the foreground job must allocate 2K words of program 
space for the USR to swap over. (See Section 2.2.3 for more informa- 
tion on the USR.) 

Figure 2-13: SJ System with Both Handlers Unloaded 
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2.2.2.2 FRUN Command — The FRUN command loads a foreground pro- 
gram into memory and starts execution. The SRUN command, which per- 
forms the same functions for system jobs, is essentially identical. You can 
also use FRUN or SRUN to start a virtual .SAV job, since these jobs do not 
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Figure 2-14: Foreground Job 
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require relocation. (See Chapt<3r 4 for more information on virtual jobs.) 
Before you start a job with FRUN, you must load all the handlers the job re- 
quires. You can use the FRUN/PAUSE option, load the handlers, then 
resume the foreground job. In any case, the handlers need to be loaded only 
before the job actually uses them. 

FRUN first opens the .REL file or virtual .SAV file, reads its first block 
(locations through 776), and determines how much memory the job re- 
quires. The job's total memory requirement is equal to the sum of the pro- 
gram itself (as indicated by location 50 in block of the file), the size of the 
impure area, the extra space fillocated with the FRUN/BUFFER:n com- 
mand, and the extra space (if any) allocated with the 
LINK/FORE GROUND:stacksize command. If you do not allocate extra 
stack space, the default stack size is used. If there is not enough memory 
available to run the job, an error message prints and the monitor dot prints 
on the terminal. 

Once FRUN gets the memory space the job needs, it sets up the job's im- 
pure area. FRUN also sets up the job context on the foreground job's stack, 
for FB systems, or in the job's impure area, for XM systems. So, when you 
first load a foreground job, it appears to be context-switched out. (See 
Chapter 3 for more information on context switching and other FB monitor 
functions.) 



System Components and Memory Layouts 2-23 



Next, FRUN loads the foreground main program into memory and 
relocates addresses in the root to reflect the current load address. Virtual 
.SAV files do not require relocation. If the job is overlaid, there is one more 
step before execution can begin. FRUN reads and relocates just the root of 
an overlaid program. Then it reads the overlay relocation information into a 
buffer. One by one, each overlay segment is then read into memory, 
relocated, and written back to disk. Finally, FRUN starts job execution. 
Figure 2-15 shows a summary of how the FRUN command loads a 
foreground job image into memory. 

2.2.2.3 Starting Foreground and System Jobs — Figure 2-16 illustrates the pro- 
cedure DIGITAL recommends for starting up a system that has both 
system jobs and a foreground job. In general, group high in memory the 
device handlers and programs that you expect to be running for the longest 
time. Lower in memory, put the handlers and programs that you plan to run 
only for a short time. This organization enables the Resident Monitor to 
reclaim free memory when you unload programs and handlers that you no 
longer need. 

In the example in Figure 2-16, the two handlers that the QUEUE program 
needs are loaded first, since the error logger and the QUEUE program are 
both intended to run as long as the system runs. (The QUEUE program 
needs handlers for the device to which it will copy files, as well as handlers 
for the devices on which those files are currently stored. The error logger 
needs no specific handler; it logs errors from any handler that calls it.) The 
SRUN command is used next to start the more important of the two system 
jobs (the error logger). Then the second system job (QUEUE) is started, 
also with SRUN. This ordering of system jobs gives the error logger higher 
priority by default than the QUEUE program. (Note that if it is not conve- 
nient for you to load the higher priority system job first, you can assign 
priorities to the system jobs with the SRUN/LEVEL:n command.) Lastly, 
the foreground job, which requires no other handler, is started with the 
FRUN command. In Figure 2-16 the foreground job, which always has the 
highest priority, is loaded last because it will only run for a short time 
before it is stopped, unloaded, and replaced by a different foreground job. 
After you stop a job by typing two CTRL/Cs, you must use the monitor 
commands to unload it and replace it with another. RT-11 does not provide 
a way for one foreground job to automatically start another. 

NOTE 

Since the system job feature permits up to six system jobs 
to execute simultaneously, it is possible to have more than 
one copy of a specific job in memory at any one time. That 
is, you can use SRUN to start a job called STAT.SYS, for 
example, and then use SRUN again to start up a second 
copy in memory of the same job from the same disk image, 
STAT.SYS. However, this procedure is valid only for pro- 
grams that are not overlaid. 

The disk image of an overlaid program is in constant use, 
since the relocated overlay segments are occasionally read 
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into memory from the file. Thus, to execute multiple copies 
of overlaid programs, you must maintain separate copies of 
the programs on disk. For example, to run two copies of an 
overlaid program called STAT.SYS, store an additional 
copy of the program on disk as STATl.SYS, and use 
SRUN to start both jobs. 

Figure 2-15: FRUN Command 
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Figure 2-16: FB System 
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2.2.2.4 Foreground Stack— The foreground job's stack is located im- 
mediately above the impure area. Its default size is 128 decimal bytes. You 
can change the size of the stack at link time by using the 
/FOREGROUND:stacksize option. 

You can also change the location of the foreground stack. To do this, use the 
/STACK:n option at link time, and specify either an octal value for the stack 
pointer or a global symbol name. If you change the stack location, you are 
responsible for allocating space for the stack in your program. 

Be careful not to let the stack overflow during execution. Since RT-11 
neither checks for this error nor makes any attempt to correct it, the most 
likely result is that your program or the impure area wiU be corrupted. 
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2.2.2.5 Foreground Impure Area — The memory locations just below the 
foreground job area contain job-dependent information. This area is called 
the impure area, and its contents are maintained by the Resident Monitor. 
Chapter 3 lists the information contained in this area. 

2.2.3 User Service Routine (USR) 

The User Service Routine (USR) is the part of the RT-11 operating system 
that provides support for the RT-11 file structure. It contains instructions to: 

Fetch device handlers 

Get the status of device handlers 

Open existing files 

Create new files 

Delete and rename files 

Close files 

In addition, the USR contains the Command String Interpreter (CSI), 
which interprets device, file, and option specifications. The default memory 
location for the USR is directly above the background area, or directly 
below the system jobs, foreground job, and loaded device handlers, if there 
are any. You can change this default location by setting an address in loca- 
tion 46 in low memory. 

The USR does not always have to be resident in memory. In fact, it was 
designed to be swappable in order to make as much space as possible 
available for user jobs when they need it. In general, for SJ and FB 
systems, the USR is needed only when file-oriented operations are required. 
The USR is always resident in the XM monitor, so swapping is not a con- 
sideration for XM jobs. 

2.2.3.1 Structure — The USR consists of two basic parts: the buffer area 
and the permanent code area. The first section, which is two blocks long, 
contains code when the USR is brought into memory. This area also serves 
as the buffer in which the USR stores a device directory segment. The sec- 
ond section contains permanent code. Figure 2-17 shows an overview of the 
USR's structure and its memory location in an SJ system. 

The first routine in the USR buffer section consists of initialization code to 
relocate pointers in the USR and KMON. This relocation code becomes ac- 
tive the first time the USR is entered after it is brought into memory. It 
relocates internal pointers in t;he USR that point to the Resident Monitor 
and to other important locations within the USR. If the USR was called 
from KMON, it also relocates pointers to RMON within KMON. 

For SJ systems, the next segments of code are: 

1. The EMT 376 processor, which contains the text and the routines to 
print fatal monitor error messages. 
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2. Code that processes the .CDFN programmed request. 

3. Routines to handle the .SRESET and .HRESET programmed 
requests. 

Figure 2-17: USR 
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For FB and XM systems, the next section of code handles the .EXIT pro- 
grammed request. The last segment of code in the buffer area processes the 
.QSET programmed request for SJ and FB monitors. A small amount of 
scratch space takes up the remainder of the two-block buffer area. 

Following the buffer area is the USR's permanent code which starts at off- 
set 2000 from the beginning of the USR. The permanent code consists of 
routines' that process the following programmed requests: 



DELETE 


.LOOKUP 


FETCH 


.RENAME 


CLOSE 


.DSTATUS 


ENTER 


.QSET (for XM only) 



The Command String Interpreter occupies the end of the USR, where the 
.GTLIN, .CSIGEN and .CSISPC programmed requests are processed. 
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2.2.3,2 Execution — The general flow of execution in the USR is straightfor- 
ward. When a fresh copy of the USR is brought into memory, its buffer area 
contains the code described in the previous section. When a program issues 
a USR programmed request, the first code to execute is the relocation code. 
This code then calls the routine to process the particular request that was 
issued. If the USR stays in mtimory, subsequent USR requests go directly 
to the routines that process th(jm. The initialization code is not called again. 

Usually, a USR request requires a device directory segment. If the correct 
segment is already in the USR buffer, the USR does not read in a fresh copy 
of that segment. If the correct segment is not in memory, or if the USR has 
no segment at all, the USR reads the directory segment into its buffer. 
When it does this, the USR stores two words of information in the Resident 
Monitor fixed offset area. BLKEY, at offset 256, contains the number of 
the directory segment currently in the USR buffer. CHKEY, at offset 260, 
contains the device's unit number in the high byte, and an index into the 
monitor device tables in the low byte. 

It can be useful to you to know under what circumstances the USR reads in 
a new directory segment. The following conditions cause the USR to read in 
a new directory segment: 

1. Anything that causes the USR to swap out. When a fresh copy of the 
USR is brought into memory, it will have no directory segment in its 
buffer and will be forced to read one from a device. 

2. Executing code in the buffer area. Since the code to process some pro- 
grammed requests is located in the USR buffer area, attempting to 
process one of those requests always causes a fresh copy of the USR to 
be brought into memory. The requests that cause this to happen are: 

.CDFN (for SJ) 

.SRESET (for SJ) 

.HRESET (for SJ) 

.QSET (for SJ and FB) 

.EXIT (if your program was loaded over any part of KMON) 

3. An SJ monitor error occurs. This situation requires the EMT 376 proc- 
essor code, which is located in the USR buffer area and causes a fresh 
copy of the USR to be read into memory. 

4. Issuing an .ENTER programmed request. This always causes the USR 
to read a fresh directory segment. 

5. Issuing a .LOOKUP programmed request with a different device or file 
specification from the previous .LOOKUP. Note that doing a 
.LOOKUP with the same device specification as the previous 
.LOOKUP does not necessarily cause the USR to read in a fresh copy 
of the same directory se,gment. This is why you cannot remove a 
volume from a given device unit, replace it with another volume, and 
expect the USR to have the new volume's directory segment in 
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memory. However, in this situation, you can force the USR to read a 4 

directory segment from the new volume by locking the USR to gain ex- 
clusive use of it, storing a value of in BLKEY (RMON fixed offset 
256), and then issuing a .LOOKUP programmed request with the same 
arguments as the previous .LOOKUP. Clearing BLKEY causes the 
USR to "forget" the current directory segment and read a fresh one 
from the new volume. 

2.2.3.3 Swapping Considerations — Because the USR does not always have 
to be resident in memory for SJ and FB systems, you have a variety of op- 
tions to consider when you design an application program. You can keep the 
USR in memory at all times (the simplest case), or you can arrange to have 
the USR swap into memory only when your program needs it. The latter 
procedure permits your program to use and extra 2K words of memory 
when the USR is swapped out. The guidelines that follow can help you 
design programs that handle USR efficiently. ^ 

In XM systems, the USR is always resident (that is, SET USR NOSWAP is 
always in effect). Of the sections that follow, only those that describe a resi- 
dent USR are meaningful for programs in XM. 

NOTE 

In general, the burden of USR swapping should be under- 
taken by the program, not by the operator who runs it. 
SET USR NOSWAP is useful to override the default ac- = 

tion of programs outside an operator's control (such as 
FORTRAN), but its use requires operators to understand 
internal programming details — a requirement that should 
be avoided if at all possible. 

Keeping the USR Resident in an SJ System 

In an SJ system, the normal location for the USR is just below the Resident 
Monitor and loaded device handlers (see Figure 2-17). If your program does 
not need the space the USR occupies, you can force the USR to remain resi- 
dent while your program is executing by issuing the monitor SET USR 
NOSWAP command before you run the program. In any case, if the space is 
not needed, the USR does not swap. Note that the USR can still slide up or 
down in memory, as Section 2.2.1 describes. 

For a FORTRAN main program, you can keep the USR resident by using 
the FORTRAN/NOSWAP command (or the /U compiler option) at compile 
time. This forces the USR to remain resident while the program is ex- 
ecuting. You cannot use this option if your FORTRAN programs require 
the extra 2K words of memory. 

Keeping the USR resident means that 2K words less memory is available to 
your program. However, the directory operations involved in file opening 
and closing and in program loading will be faster because this arrangement 
eUminates swapping and disk I/O. In addition, the program will have a ' 

much simpler design. To keep the USR resident, a MACRO program should 
avoid issuing a .SETTOP request for memory above the base of the USR. 
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Remember that even though the USR is set to NOSWAP, there are some 
programmed requests that can cause a fresh copy of the USR to be brought 
into memory. For an SJ system, these requests are .CDFN, .SRESET, 
.HRESET, .EXIT, and .QSET. If the USR is swappable and if the 
background program issues a , SETTOP request for memory above the base 
of the USR, the USR loads into the area specified by the contents of loca- 
tion 46 in low memory. If location 46 contains 0, as it should when you in- 
tend to keep the USR resident, the USR loads in its usual place, below 
RMON. However, if for any reason you move a different value to location 46 
and then execute one of the recjuests that loads a fresh copy of the USR, the 
USR will then load into the area you specified. If you execute a program 
that keeps the USR resident, tltie monitor ignores the contents of location 46. 

Allowing the USR to Swap with an SJ MACRO Program 

The only reason to allow the U SR to swap in an S J system is to gain access 
to the extra 2K words of memory that swapping makes available. To enable 
USR swapping, make sure that the SET USR SWAP command is in effect. 
(This is the default condition.) 

A MACRO program gains access to the 2K words of memory because its 
high limit requires it, or because it does a .SETTOP to an address within 
the USR area. (Refer to Figures 2-9 and 2-10 for a summary of how the 
RUN and R commands load programs that overlay the USR area.) When 
the program issues a programmed request that requires the USR, the part 
of the program that occupies the USR area is written out to SWAP.SYS, 
and a fresh copy of the USR is brought into memory from the monitor file 
on the system volume. Location 46 should contain a value of if you want 
the USR to swap into memory at its default location. If you want it 
elsewhere, put the starting address into location 46 during you program's 
initialization routine. When the programmed request completes, the part of 
the program in SWAP.SYS is copied back into memory, overlaying the 
USR. This sequence of events occurs for each programmed request that re- 
quires the USR, even if your program issues two or more requests in a row. 

To make more efficient use of the USR, your program can issue the .LOCK 
programmed request before any other USR requests. This swaps part of 
your program out, reads the USR in, and returns to your program. After 
this, the USR remains in memciry at the location you specified in location 46 
(if any). You can now issue a number of USR programmed requests and 
avoid the overhead of USR swapping. When your program next needs the 
2K words of space, use an .U^fLOCK request to release the USR. 

When the USR is swappable, it is important that you put it in a safe place in 
your program. This means that the area the USR will swap over must not 
contain code or data that will be needed at the same time the USR is in 
memory. The following is a list; of code and data that must not be overlaid 
by the USR: 

• Device block and/or CSI or .GTLIN file description string for the 
current request 

• Active device handlers 
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Active completion routines 

Active interrupt service routines 

Active I/O buffers 

Queue elements from .QSET 

I/O channels from .CDFN 

The program stack 

The memory Ust from .DEVICE 

Trap service routines from .SPFA and .TRPSET 

Code executed between the .LOCK and .UNLOCK requests 

You can control USR swapping by careful use of the .SETTOP request. A 
typical practice that many system utility programs use is to issue a .SET- 
TOP request to obtain space up to the base of the USR. The programs then 
perform all their USR operations. Finally, the programs issue an additional 
.SETTOP request to obtain as much memory as possible, if necessary. 

Another situation to be aware of occurs when a program issues a .SETTOP 
request for more memory than is available. In this case, the program is 
given only the amount of memory that is available. After issuing a .SET- 
TOP request, a program must always use the value returned to RO (or loca- 
tion 50 in low memory) as the true high limit of the program. For example, a 
program can issue a .SETTOP request for memory above the base of the 
USR when the USR is set to NOSWAP. However, the value returned to the 
program as its true high Umit is just below the base of the USR. 

Allowing the USR to Swap with an SJ FORTRAN Program 

As with a MACRO program in an SJ system, the only reason to permit the 
USR to swap with a FORTRAN program is to gain access to an additional 
2K words of memory. The USR normally swaps over the FORTRAN OTS 
(Object Time System). However, problems occur when the FORTRAN OTS 
and the program together are less than 2K words long. In this case, the 
USR swaps over the program's impure data area, with unpredictable 
results. (Since this error is frequently made by inexperienced programmers, 
setting the USR to NOSWAP and retrying a program is the first thing you 
should do when debugging a FORTRAN program that doesn't execute 
properly.) And, unlike MACRO, USR swapping does not depend on your 
program's high limit — that is, if the USR is allowed to swap, it most 
definitely will swap. So, do not permit USR swapping unless your program 
really needs the extra memory. To enable swapping for a FORTRAN pro- 
gram, make sure the SET USR SWAP command is in effect, and eliminate 
the /NOSWAP or the /U option at compile time. 

You have ah-eady read about the role that location 46 plays in determining 
where the USR will swap. For a FORTRAN program, the FORTRAN OTS 
places a value in location 46 to set up the USR swapping location. It is im- 
portant to understand where and how the USR swaps so you can design 
your FORTRAN program correctly. 
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The FORTRAN compiler examines the sections of your program and sorts 
them based on two major attributes: read-only versus read-write, and pure 
code versus data. Generally, jprogram instructions are read-only, and pro- 
gram data is read-write. If you use assembly language routines, use the 
same p-sects as the FORTRAN compiler. That is, place pure and read-only 
data in section USER$I, and impure data in USER$D. The compiler forces 
p-sects into the order shown in Table 2-7. 

Table 2-7: P-sect Ordering for FORTRAN Programs (Low to High 
Memory) 



Section 
Name 


Attiibutes 


Contents 


OTS$I 


RW,I,LCL,REL,CON 


Pure code and data for the 
OTS initialization module 


OTS$P 


RW,D,GBL,REL,OVR 


Pure tables of addresses of 
other OTS modules 


SYS$I 


RW,I.LCL,REL,CON 


RT-11 SYSLIB routines 


USER$I 


RW,I,LCL,REL,CON 


Program's pure code and 
read-only data 


$CODE 


RW,I,LCL,REL.CON 


Start of program; read-write 
data 


OTS$0 


RW,I,LCL,REL CON 


OTS routines sensitive to 
USR swapping 


SYS$0 


RW,I,LCL,REL,CON 




$DATAP 


RW,D,LCL,REL,CON 


Constants 


OTS$D 


RW,D,LCL,REL,CON 


Pure data referenced by the 



OTS$S 



RW,D,LCL,REL,CON 



OTS module 

Scratch storage referenced 
by the OTS module 



SYS$S 


RW,D,LCL,REL,CON 




$DATA 


RW,D,LCL,REL,CON 


Local variables 


USER$D 


RW,D,LCL,REL,CON 


Program's impure data 


.$$$$. 


RW.D,GBL,REL,OVR 


Blank COMMON 


Named COMMON 






blocks 


RW,D,GBL,REL,OVR 





This ordering collects all pure sections before impure data in memory. The 
USR can safely swap over sections OTS$I, OTS$P, SYS$I, USER$I, and 
$CODE. Figure 2-18 shows the arrangement of components when a 
FORTRAN Program is loaded into memory. The global symbol $$OTSI 
marks the start of the pure code area. The global symbol $$OTSC marks its 
end, and the beginning of the iinpure data area. FORTRAN puts the value 
of $$OTSI into location 46, and the USR swaps into memory starting at 
that address, thus overlaying the first 2K words of your program. 
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Figure 2-18: A FORTRAN Program in Memory 
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As with a MACRO program, your FORTRAN program should not have 
certain instructions or data in the area where the USR will swap. As a 
general rule, the following items should not be in the USR swap area: 

• Routines that request USR functions (such as lENTER and 
LOOKUP) 

• Data structures for USR requests 
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• Interrupt service routines 

• Completion routines 

• Data areas for interrupt service routines and completion routines 

The FORTRAN system itself must also be concerned with USR swapping 
and its inherent restrictions. For example, the p-sect OTS$0 contains the 
FORTRAN OTS routines to open files. This p-sect follows $CODE in the 
p-sect ordering. If the start of OTS$0 is within 2K words of $$OTSI, the 
essential information for the file operation is stored on the job stack before 
the USR swaps over the code in OTS$0. 

The best way to make sure thjit the USR swaps into a safe place in your 
FORTRAN program is to examine the link map to determine if the USR 
will swap over restricted sections. That is, see if the first 2K words above 
$$OTSI can be overlaid safely. If not, relink the program and change the 
order of object modules and libraries you specify to the linker. One problem 
is caused by using SYSLIB routines that place important USR data in the 
lower 2K words of the job image. An example is the IFETCH routine, which 
uses a device block in the program. The USR swaps over the device block 
just before it is used, causing an error. To avoid a situation like this, do not 
set up device names as constants for a SYSLIB call. Instead, use DATA- 
initialized variables. This ensui-es that the information will be stored high 
enough in the job image to avoid being overlaid by the USR. 

For more information on this topic, see the RT-11/RSTS/E FORTRAN IV 
User's Guide and the PDP~11 FORTRAN Language Reference Manual. 

Keeping the USR Resident in an FB System 

As with an S J system, the easier way to deal with the USR in an FB system 
is to keep it resident. Use the SET USR NOSWAP command, or the 
/NOSWAP (/U) FORTRAN compiler option. This arrangement is suitable if 
the background, foreground, and system jobs have enough memory. The 
USR is brought into memory at its usual place, just below any loaded 
handlers and below the foreground job and it remains in memory during 
program execution. Neither job has to allocate program space for the USR, 
and programs execute faster without the overhead of USR swapping and 
disk I/O. 

The important issue in an FB system with the USR resident is determining 
which job should have control of the USR. Because only one job can use the 
USR at a time, both jobs must be aware of sharing this resource. Since a 
program in an SJ system can lock the USR in order to process a number of 
USR programmed requests, in an FB system, either the background job or 
the foreground job can lock the: USR to gain exclusive use of it. 

The .LOCK request gives ownei-ship of the USR to one job. The .UNLOCK 
request releases the USR, making it available for the other job. The request 
.TLOCK can determine whether or not the other job has exclusive owner- 
ship of the USR. It permits a program to try for a .LOCK, but to continue 
with execution if the attempt fails. 
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The LOCK/UNLOCK system permits one job to lock out another for a con- 
siderable length of time. During a lockout, interrupt service and completion 
routines can run, but not mainline code. This could cause serious difficulties 
in a real-time foreground program. There are some ways to minimize or 
eliminate this lockout problem: 

1. Be sure to separate USR operations from real-time operations. 

2. Avoid using devices with slow directory operations, such as cassette, 
magtape, and DECtape II, 

3. Organize your real-time foreground program so that real-time opera- 
tions are in interrupt service routines and completion routines and will 
not be affected if the mainline code is locked out with a pending USR 
request. 

Typically, a real-time foreground job can be organized in three parts: an in- 
itialization phase, which opens all required channels and begins real-time 
operations; a real-time phase, which does interrupt service and I/O opera- 
tions; and a completion phase, which stops real-time activity and closes the 
channels. With this arrangement, the background program can perform 
USR operations during the real-time phase without locking out the 
foreground. The foreground program can use .LOCK and .UNLOCK to pre- 
vent interference from the background job during initiaUzation and comple- 
tion phases. 

Swapping Considerations for Background Jobs 

When either the background job or the foreground job needs the extra 2K 
words of memory that swapping the USR provides, both jobs must be con- 
cerned with USR swapping. The general concerns for background jobs are 
those listed in the previous sections. 

The easiest approach for the background job is to swap the USR into its 
default location, the highest 2K words of program space. If this is not 
convenient for any reason, the background job can select any other con- 
tiguous 2K words of program space. In this case, it must also put the start- 
ing address of the USR swap area into location 46 in the system com- 
munication area. This location is context-switched in the FB system, so it 
always contains the correct value for the job that is currently executing. 

The background job must not place any USR-sensitive code or data in the 
area where the USR will swap. In addition to the Ust in the section Allowing 
the USR to Swap with an SJ MACRO Program, the following items must 
not be in the USR swap area: 

• Memory Ust from the .CNTXSW request 

• Active message buffers 

• Code containing the .LOCK or .TLOCK requests 

You must also be careful that the background job does not lock the USR for 
an unreasonable length of time so it can block the foreground job from 
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running. If you lock the USR in a background job, remember to unlock it as 
well. 

Swapping Considerations for Foreground Jobs 

If the background job issues a .SETTOP that causes the USR to swap, or if 
the background job is large enough to force the USR to swap, the 
foreground job must be concerned with USR swapping. However, while the 
background job can simply allow the USR to swap into its default position 
(the highest 2K words of the beickground job area), the foreground job has 
no default location for the USR. It must allocate 2K words within its pro- 
gram bounds in which to swap the USR — space that must not contain any 
USR-sensitive code or data. The foreground job must also place the starting 
address of that space in location 46 in the system communication area. This 
location is context-switched during normal foreground/background execu- 
tion, so it always contains the correct swapping address for whichever pro- 
gram is currently executing. 

The foreground program could also be concerned with sharing the USR 
with the background job. The .LOCK/.UNLOCK requests can give the 
foreground job exclusive ownership of the USR to prevent interference by 
the background job. The foreground job should avoid keeping the USR per- 
manently locked, which sometimes happens strictly because of a program- 
mer's oversight. 

2.2.4 Keyboard Monitor (KMON) 

The Keyboard Monitor (KMO]>J) is the part of the RT-11 system that 
provides the communication link between you at the console terminal and 
the rest of the RT-11 system, I^eyboard monitor commands permit you to 
assign logical names to devices, load device handlers, run programs, control 
foreground/background operations, control system jobs, invoke indirect 
command files, and examine or modify memory locations. KMON is 
brought into memory when the background job completes. When KMON is 
in memory, the USR is also present directly above it. 

The Keyboard Monitor consists of a root segment and a number of overlays 
that contain the command processors. KMON runs as an ordinary 
background job, in user mode. The root segment is contained in the p-sect 
RT-11. See Table 2-6 for a summary of all monitor p-sects. 

When KMON interprets a keyboard monitor command that you type at the 
terminal, it expands the command text into an internal indirect file. For 
example, the command COPY MYFILE DL:MYFILE < RET > expands 
internally into: 

R PIP<RET> 

DLMYFILE = DK:MYFILE<RET> 

KMON stores this internal indirect file in the command expansion buffer 
area. KMON creates space in itnemory for this buffer area immediately 
above the USR. When KMON and the USR slide up or down in memory, the 
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command buffer spaces moves with them. Figure 2-19 shows the Keyboard 
Monitor in memory. 

Figure 2-19: Keyboard Monitor 
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Chapter 1 of the RT-11 System User's Guide gives an overview of KMON 
command processing. The RT-11 Installation and System Generation 
Guide describes how to remove individual commands or groups of 
commands from a system you create through the system generation 
process. If you are interested in modifying KMON itself to change the 
monitor command set, obtain the microfiche listings of the commented 
sources. Extensive comments in KMON sources outline the procedure for 
adding new commands and changing existing commands. Note that 
because the procedure is very complex, DIGITAL does not recommend 
modifying the keyboard monitor commands. 



2.3 Sizes of Components 



Table 2-8 shows the sizes of some of the components in the distributed 
RT-11 systems. 

If you are not using a distributed system, and you need to know the sizes of 
the components, you should follow the guideUnes in the next few sections. 
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Table 2-8: Sizes of Distributed Components in Memory 

Monitor KMON USR RMON 



BL 


17000 


2K 


1857 


(base-line) 


octal bytes 


words 


decimal words 


SJ 


17000 


2K 


1996 




octal bytes 


words 


decimal words 


FB 


17000 


2K 


4220 




octal bytes 


words 


decimal words 



2.3.1 Size of the USR 

For SJ and FB systems, the size of the USR is always 2K words. For XM 
systems the USR, which is always resident, is somewhat larger. Your run- 
ning program can determine the exact size of the USR by examining 
RMON fixed offset 374, USRAREA, which contains the size of the USR 
in bytes. 

2.3.2 Size of KIVION 

The size of KMON is the same as the size of the p-sect RT-11. Examine the 
link map that resulted from the system generation for your system to ob- 
tain this value. 



2.3,3 Size of RIVION 

To determine the size of RMON, issue the SHOW CONFIGURATION moni- 
tor command. This command prints the base address of RMON. If your 
system has 28K words of lov/ memory, subtract the base of RMON from 
160000 to obtain RMON's size. If you have an LSI system with 30K words of 
low memory, subtract the base of RMON from 170000. If your system has 
fewer than 28K words of memory, subtract the base of RMON from the 
highest memory address. The resulting value represents the size of RMON 
plus the size of the system device handler. 

2.3„4 Size of Device IHandiers 

The size of each device handler, in bytes, is contained in location 52 of the 
handler's .SYS file. You can also obtain this value by issuing a .DSTATUS 
programmed request on the device from a running program. 
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Chapter 3 
Resident Monitor 



The main purpose of the Resident Monitor (RMON) is to provide services to 
running programs and to the IKeyboard Monitor, The services include field- 
ing traps and interrupts, providing the programmed requests, and acting as 
the central manager of the desvice-independent I/O system. In a multi-job 
system, the monitor also arbitrates the demands of up to eight jobs for proc- 
essor time. 

This chapter describes the functions of the Resident Monitor that are gen- 
erally common to all RT-11 systems. It provides information on the mon- 
itor's terminal service for a single console terminal. (See Chapter 5 for infor- 
mation on multi-terminal systems.) It also describes how clock interrupts 
are handled and explains how timer support is implemented. The queued 
I/O system is discussed, scheduling for multi^job systems is described, and 
the system job feature is introduced. Lastly, information on the Resident 
Monitor's data structures is provided. 



3.1 Terminal Service 



i: 



RT-11 provides terminal service through the Resident Monitor. Terminal 
service is always resident, and it is part of RMON itself. Because of the way 
RT-11 implements terminal service, no handler is involved in the 
interaction between you at the terminal and the running system. Thus, 
terminal service is distinct from the services provided through the TT 
handler. (The TT handler implements .READ and .WRITE programmed 
requests for the console terminal.) It is designed to be a good interface 
between a person and the system, rather than an interface between a 
peripheral device and the system. 

As part of the resident terminal service, RMON provides special pro- 
grammed requests for terminal I/O. Because it uses ring buffers to 
implement the terminal service, RMON provides support for Une-by-line 
editing. The terminal input interrupts are always enabled, which means 
that you can get the system's attention at any time by typing CTRL/C, 
CTRL/B, CTRL/F, and so on. You can also type ahead to the system 
without losing characters. 

The ring buffers are the heart: of the terminal service implementation. In 
SJ, one input ring buffer and (me output ring buffer are located in RMON. 
For FB and XM systems, each job has its own set of ring buffers located in 
its impure area. The ring buffers store text in a buffer zone between you at 
the terminal and a running program in memory. The default size of the 
input ring buffer is 134 decim^al bytes; the default size of the output ring 
buffer is 40 decimal bytes. 
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3.1.1 Output Ring Buffer 

An output ring buffer consists of the buffer area, three pointers, and a byte 
count. The buffer, or ring, itself is a block of bytes reserved for storing 
characters. Two of the three pointers store and retrieve characters. The 
PUT pointer marks the location where the next character will be stored and 
is used by the programmed requests that fill the buffer, such as .TTYOUT, 
.TTOUTR, and .PRINT. The GET pointer marks the next character to be 
retrieved and is used by the output interrupt service routine that sends 
characters to the terminal. The third pointer, HIGH, points to the first 
memory location past the buffer. Lastly, the monitor maintains a byte 
count for the number of characters currently in the buffer. Figure 3-1 
shows an output ring buffer in memory just after the system was 
bootstrapped. 



Figure 3-1: Output Ring Buffer 
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3.1.1.1 Storing a Character In the Output Ring Buffer — The output ring buffer 
is filled by characters that are passed by .TTYOUT, .TTOUTR, and 
.PRINT. Characters that echo what you type on the terminal are also stored 
here, including sets of backslashes to enclose text you rub out with the 
DELETE key on a hard copy terminal. To store a character in the output 
ring buffer, the monitor first compares the buffer size to the byte count to 
check for room. If there is no room, the character cannot be stored. In FB 
systems, this condition is sufficient to block a job if the job is doing output. 
(If the output is the result of echoing, it is simply discarded.) If there is 
enough room, the monitor checks to see if the PUT pointer is equal to the 
HIGH pointer. This check ensures that the PUT pointer is pointing to a 
location that is within the buffer. If the PUT and HIGH pointers are the 
same, the monitor subtracts the size of the buffer from the current PUT 
pointer to obtain the new PUT pointer. By doing this, the monitor "wraps" 
around the ring to move from the highest address in the buffer to the lowest 
one. 
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Next, the monitor moves a by te into the buffer and it increments both the 
PUT pointer and the byte count. Figure 3-2 shows how characters are 
stored in the output ring buffer. 

Figure 3-2: Storing Characters in the Output Ring Buffer 
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3.1.1.2 Removing a Character from the Output Ring Buffer — The terminal out- 
put interrupt service routine removes characters from the output ring buf- 
fer. If the character count is 0, the routine terminates. The routine checks to 
see if the GET pointer is equal to the HIGH pointer. If it is, this means it is 
time to "wrap" around the ring to move from the highest address in the buf- 
fer to the lowest one. The wrapi routine subtracts the size of the buffer from 
the current GET pointer to obtain the new value of the GET pointer. This 
check ensures that the GET pointer is pointing to a location that is within 
the buffer. 

Next, the output interrupt service routine removes one character through 
the GET pointer and prepares to send it to the terminal. It increments the 
GET pointer and decrements the byte count. 

3.1.2 Input Ring Buffer 

The input ring buffer is similar to the output ring buffer except that in addi- 
tion to the GET, PUT, and HIGH pointers, it has a LOW pointer that 
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points to the first byte of the buffer. This pointer is useful when the 
pointers are moving backward through the buffer as a result of CTRL/U or 
DELETE. It indicates when to "wrap" the buffer in the reverse direction, 
from the lowest address to the highest. 

The monitor also keeps a count of the number of lines that are stored in the 
input ring buffer. A line is any sequence of characters terminated by hne 
feed, CTRL/Z, or CTRL/C. (Each time you type a carriage return at the ter- 
minal, RT-11 stores two characters in the input ring buffer: a carriage 
return and a line feed.) In normal mode, the monitor does not pass input 
characters to a program until an entire line is present. This is why you can 
use DELETE to rub out a character and CTRL/U to remove an entire line 
when you are typing at the terminal. Since the monitor provides for hne-by- 
line editing, application programs need not have this overhead themselves. 

In special mode, however, the monitor passes bytes to a program exactly as 
they are typed on the terminal. In the latter case, the program itself must 
be able to interpret editing characters such as DELETE and CTRL/U. 

NOTE 

Special mode does not provide the complete transparency 
required to handle devices other than terminals — such as 
communication Unes — through the Resident Monitor ter- 
minal service. You can achieve transparency through the 
multi-terminal feature of RT-11 by using the "read pass- 
all" and "write pass-all" modes. These are described in 
Chapter 5. 

Figure 3-3 shows the input ring buffer iust after the system was 
bootstrapped. 

Figure 3-3: Input Ring Buffer 
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3.1.2.1 Storing a Character in tlie Input Ring Buffer— When you type 
characters at the terminal, the keyboard interrupt service routine stores 
them in the input ring buffer. First, the routine checks to see if there is room 
in the buffer. If there is no room, it rings the terminal bell (by putting a bell 
character in the output ring buffer). If there is room, the routine increments 
the byte count, increments the PUT pointer, wrapping it if necessary, and 
stores the byte in the ring buffer. It also increments the line counter, if the 
character typed is a valid line terminator. Figure 3-4 shows how characters 
are stored in the input ring buffer. 

Figure 3-4: Storing Characters in the Input Ring Buffer 

GET-i i-LOW 




BYTE COUNT: 19 



LINE COUNT: 1 



3.1.2.2 Removing a Character from the Input Ring Buffer— The monitor 
removes characters from thcs input ring buffer when it processes the 
.TTYIN, .TTINR, .GTLIN, .CSIGEN, and .CSISPC programmed requests. 
First it increments the GET pointer, wrapping around the ring if necessary. 
Then it gets a byte from the* buffer and decrements the byte count. It 
decreases the line count as well if the character is a valid line terminator. 

3.1.3 High Speed Ring Buffer 

RT-ll provides an optional, additional high speed ring buffer that you can 
enable by setting the conditional HSR$B in SYCND.MAC to 1 and 
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reassembling the monitor. This adds an extra input ring buffer to RMON; it 
adds an extra output ring buffer only if your system has multiple DL 
interfaces. 

When the high speed ring buffer is present, all character processing and in- 
terpretation is performed at fork level. The high speed buffer is used to pass 
characters from interrupt level to fork level. The advantage of having the 
high speed buffer is that it allows the monitor to handle short bursts of 
characters coming in at a very high rate. This is useful for systems with 
VTIOO or other intelligent terminals that report their status by sending a 
burst of information to the host computer. It is also useful for connecting 
one computer to another over a serial line. 

The disadvantage to using the high speed ring buffer is that a .FORK call is 
required for each burst of characters, and, thus, overall terminal service 
may be slower. 

3.1.4 Terminal I/O Limitations 

Terminal input and output Umitations are completely separate; you use dif- 
ferent methods to change each of them. 

RT-11 accepts terminal input in either of two forms: a line at a time, or a 
character at a time. In Une mode, characters you type at the terminal are 
stored in the input ring buffer until you type a valid Une terminator such as 
carriage return, line feed, CTRL/Z, or CTRL/C. Only then does a running 
program receive the Une of data. The factor Umiting the length of the input 
Une is the size of the input ring buffer. (The setting of the terminal right 
margin bears no relation to the length of the input Une.) In RT-11 V04, the 
default length is 134 decimal bytes, but you can change this through the 
system generation process. Any attempt to insert characters beyond this 
Umit causes the terminal beU to ring, and the extra characters are lost. The 
Command String Interpreter can accept only 81 characters per Une. Most 
utiUty programs, including PIP and BASIC-11, use the CSI to obtain Unes 
of data from the terminal. 

In character mode, a running program receives each character immediately 
after you type it at the terminal. In this mode, you can enter any number of 
characters without using a Une terminator. EDIT uses character mode, and 
can thus accept Unes of any length. 

The length of terminal output Unes is not related to the size of the output 
ring buffer; instead, it is related to the setting of the terminal right margin. 
Use the SET TT: WIDTH = n command to adjust the right margin. (See the 
RT-11 System User's Guide for details on SET TT: WIDTH and SET TT: 
CRLF.) 



3.1.5 Control Functions 

A special aspect of RT-11 's terminal service is its response to control 
characters that you type at the terminal. The monitor handles each 
character differently, depending on the special function of each one. The 
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following sections describe the different processes involved for the various 
control characters. 

3.1 .5.1 CTRL/C — When you type one CTRL/C at the terminal, the terminal 
interrupt service routine puts it into the input ring buffer, just as it would 
any other character. The monitor treats it as a line delineator and passes it 
to the running program. 

However, if you type two CTRL/Cs in a row, the monitor processes them en- 
tirely differently. Instead of passing them directly to the program, the 
monitor aborts the running j obi. A program can use the .SCCA programmed 
request to intercept CTRL/C" and prevent the abort (see the RT-11 
Programmer's Reference Manual for a description of .SCCA). 

3.1.5.2 CTRL/0 — When the terminal interrupt service routine detects a 
CTRL/O, it never places the character in the input ring buffer, even if it is in 
special mode. The monitor simply toggles a flag in the impure area. (In FB 
and XM systems, this flag is the sign bit of the output ring buffer byte 
count.) 

The first time you type CTRL/0, the monitor echoes it, then clears the out- 
put ring buffer byte count. It empties the ring by setting the GET and PUT 
pointers equal to each other, and output from a running program is thrown 
away. In FB and XM systems, this can unblock a job waiting for room in 
the output buffer. The next time you type CTRL/0 or your job issues the 
.RCTRLO programmed request, normal output resumes. 

3.1.5.3 CTRL/S and CTRL/Q — RT-11 implements terminal synchronization 
through the characters CTRL/S and CTRL/Q. CTRL/S, or XOFF, is a signal 
that stops a host computer irom transmitting data to a terminal. The 
CTRL/Q, or XON, signal causess the computer to resume the transmission. 
Although XOFF has many uses, RT-11 supports only the two most 
common. 

In a typical situation, you may be doing program development using a 
video terminal. When you use the TYPE monitor command to review a file, 
the text scrolls past faster than you can read. You can type CTRL/S to stop 
the display so that you can read it, and then type CTRL/Q to resume the 
scrolling. You initiate the XOFF yourself, in this case. 

In another situation, the computer may send characters to a terminal faster 
than the terminal can display them. So, the terminal itself sends the XOFF 
signal to the computer, empties its internal silo, and sends XON when it is 
ready to accept more data. Thiis procedure is transparent to you. 

A flag in RMON, called XEDOFF, indicates the XOFF/XON status. Typ- 
ing CTRL/S sets the flag; typhig CTRL/Q clears it. When XEDOFF is set, 
the monitor disables terminal output interrupts and stops emptying the 
output ring buffer. See the RT-11 System User's Guide for a description of 
the SET TT: NOPAGE command, which disables CTRL/S and CTRL/Q 
processing for FB and XM systems, and for those SJ systems with the 
multi-terminal special feature. 
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3.1.5.4 CTRL/B, CTRL/F, and CTRL/X — In FB and XM systems CTRL/B and 
CTRL/F direct terminal I/O to the correct job. (In SJ systems these 
characters have no special meaning.) CTRL/X performs the same function 
for systems with system jobs. (See Section 3.5.9 for more information on 
communicating with system jobs.) The CTRL/B, CTRL/F, and CTRL/X 
characters are not put into the input ring buffer. Instead, they are recogniz- 
ed by the input interrupt service routine (unless SET TT: NOFB is in effect, 
in which case the characters have no special meaning) and the monitor 
switches the set of ring buffers it is using. 

The interrupt service routine uses two control words, TTOUSR and 
TTIUSR, to point to the impure area of the correct job. The job's identifica- 
tion is stored in a special buffer in the impure area. The foreground j ob ID is 
F>; the background job ID is B>; the ID for a system job is its job name. 
When terminal I/O is directed to a different job, the new job's identification 
prints on the terminal. 

3.1.6 SET Options Status Word 

The word TTCNFG in the Resident Monitor is a status word that indicates 
which terminal SET options are in effect. For multi-terminal systems, each 
terminal control block has a status word similar to TTCNFG. TTCNFG 
reflects the status of the SCOPE, PAGE, FB, FORM, CRLF, and TAB op- 
tions. Table 3-1 shows the meanings of the bits. Unused bits are reserved 
for future use by DIGITAL. 

Table 3-1: SET Options Status Word 

Bit Meaning When Set 



SET TT: TAB option is in effect. 

1 SET TT: CRLF option is in effect. 

2 SET TT: FORM option is in effect. 

3 SET TT: FB option is in effect. 
4-6 Reserved. 

7 SET TT: PAGE option is in effect. 

8-14 Reserved. 

15 SET TT: SCOPE option is in effect. 



To get the status word and current width of the terminal (in systems 
without the multi-terminal special feature), use the following lines of code: 

MOV ®#30,Rn 

MOV - (Rn),STATUS 

MOVB -6(Rn),WIDTH 

Use the following additional line to obtain the value of the current carriage 
or cursor position (a value of means the cursor or carriage is at the left 
margin): 



MOVB -1(Rn),POSIT 
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3.2 Clock Support and Timer Service 

You do not need a system clock in order to run RT-11 on a PDP-11 com- 
puter. However, if your computer does have a clock, RT-11 can provide 
basic support for keeping time of day, or it can provide timer service — 
standard with FB systems, and a system generation special feature for SJ 

systems. 

3.2.1 SJ Systems Without Timer Service 

An SJ system without the timer feature (the default condition) provides 
basic support for a system clock. Essentially, RT-11 keeps track of the 
time of day, but does not provide a means to implement mark time or timed 
wait requests. 

The bootstrap routine looks for a clock on the system. If it finds one, it sets 
the clock bit in RMON's configuration word at fixed offset 300. If the clock 
has a CSR (Control and Status Register), the bootstrap turns the clock on. 
If the clock does not have a CISR (as is the case with some LSI- 11 and 
PDP~ll/23 computers), no executing routine can turn the clock on or off; 
there may be a switch for the clock on the front panel. 

RMON maintains the time of (day in a two-word counter. The counter is 
called $TIME (high-order word) and $TIME -1-2 (low-order word). RT-11 
stores time of day as the numbesr of ticks since midnight if you set the time 
with the monitor TIME command. If you do not set the time, RT-11 stores 
the number of ticks since the system was last bootstrapped. 

RT-11 supports KWll-L and similar line frequency clocks, and KWll-P 
programmable clocks. (Support for the programmable clock is a feature that 
you select through system generation.) The default interrupt frequency for 
the clocks is the same as the hne frequency. That is, the clock interrupts 60 
times per second with 60 Hz power, and 50 times per second with 50 Hz 
power. Each time the clock interrupts, it adds one tick to the two-word time 
of day counter. 

In a simple system with a clock and no timer service you can use the 
monitor TIME command to set the time of day or get the current time. A 
running program can use the .GTIM programmed request to obtain the cur- 
rent time, and .SDTTM to set it. 

3.2.2 Systems Witli Timer Service 

Timer service is always included in FB and XM systems. It is a system 
generation special feature for S.J systems. Timer service provides three ex- 
tra programmed requests: the mark time request (.MRKT), the cancel mark 
time request (.CMKT), and the timed wait request {.TWAIT, in FB and XM 
only). In addition, another system generation special feature provides 
device time-out support through the time-out macro (.TIMIO) and the 
cancel time-out macro (.CTIMIO), which are described fully in Chapter 7. 

Because timer support itself requires the fork queue, selecting this feature 
in S J results in real, rather than simulated, fork processing. (Usually in SJ a 
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.FORK request returns immediately to the following instructions.) With a 
real fork queue in SJ, .FORK requests are serialized and do not interrupt 
one another. For more information on the .FORK request, see Chapter 6. 

To implement timer services, RT-11 uses a timer queue, which is a linked 
Ust of queue elements, sorted in order of expiration time. The element that 
expires soonest is at the head of the queue. The ,MRKT, .TWAIT, and 
.TIMIO requests use the timer queue. They schedule completion routines to 
be executed after a certain time interval elapses. 

The monitor uses the timer queue internally to implement the .TWAIT pro- 
grammed request, which causes the job that issues it to be suspended. The 
monitor places a timer request in the timer queue, with the .RSUM pro- 
grammed request code as its completion routine. The job waits until the 
specified time interval has elapsed. Execution resumes when the monitor 
itself issues the .RSUM request as a completion routine. 

Figure 3-5 shows the format of a timer queue element. It includes the sym- 
boUc names and offsets as well as the contents of each word in the data 
structure. Note that time is stored as a two-word number — a modified ex- 
pression of the number of ticks until the timed wait expires. 

Figure 3-5: Timer Queue Element Format 



NAME 


OFFSET 


CONTENTS 


C.HOT 





HIGH-ORDER TIME 


CLOT 


2 


LOW-ORDER TIME 


CLINK 


4 


LINK TO NEXT QUEUE ELEMENT; IF NONE 


CJNUM 


6 


OWNER'S JOB NUMBER 


CSEQ 


10 


OWNER'S SEQUENCE NUMBER ID 


CSYS 


12 


-1 IF SYSTEM TIMER ELEMENT; 
-3 IF .TWAIT ELEMENT IN XM 


CCOMP 


14 


ADDRESS OF COMPLETION ROUTINE 






THREE ADDITIONAL WORDS ARE PRESENT IN 
XM SYSTEMS. THEY ARE UNUSED, AND ARE 
RESERVED FOR FUTURE USE BY DIGITAL. 



To store the time of day in all systems with timer support, RT-11 uses a 
two-word pseudo clock called PSCLOK (low-order word) and PSCLKH 
(high-order word). In this pseudo clock RMON stores the time, in ticks, that 
has elapsed since the system was bootstrapped. Each clock interrupt adds 
one tick to the counter. Two other words — $TIME and $TIME + 2 — con- 
tain a constant that, when added to the value of the pseudo clock, yields the 
current time of day. 
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The monitor uses the pseudo clock to implement timer requests. When a 
new queue element is put on the queue, the monitor adds the low-order word 
of the pseudo clock to the two-word time value in the queue element and it 
stores the resulting value, a modified time, in the queue element time 
words. Whenever the pseudo clock carries into the high-order word (approx- 
imately every 18 minutes), the monitor subtracts 1 from the high-order 
word of time in each pending timer queue element. The element expires 
when the high-order time word is and the low-order time word is less than 
or equal to the pseudo clock low-order word. This method of storing time in- 
formation means that handling timer requests requires only test and com- 
pare instructions, which execute rapidly, and a pass over the queue roughly 
every 18 minutes to correct the time words. 

Every time the system clock interrupts, the monitor increments the pseudo 
clock. It then checks the first element in the timer queue. If the high-order 
word of the timer element is and the low-order word is greater than the 
low-order word of the pseudo clock, the element has expired. The monitor 
removes it from the timer queue and processes it as a completion routine for 
the correct job. The monitor continues to check the timer queue until it 
finds an element that has not yet expired or the queue is empty. 

There are several uses for system timer elements. If C.SYS is - 1, the ele- 
ment is being used by .TIMIO for device time-out support, or by RMON for 
multi-terminal device time-out. If C.SYS is - 3, the element is being used to ' 
implement a .TWAIT request in an XM system. For .MRKT and other 
.TWAIT requests, C.SYS is 0. 

In XM, completion routines that have - 1 in C.SYS are run in kernel mode 
and the queue element is discarded. That is, the queue element is not Unked 
into the list of available elements. If C.SYS is - 3, the completion routine is 
still run in kernel mode. However, the queue element is Unked into the 
available queue when the completion routine is run. (The timer queue ele- 
ment is used as the completion qiueue element.) In all other cases, the queue 
element is linked into the available queue and completion routines run in 
user mode. (Chapter 4 provides more information on extended memory 
systems.) 

3.3 Queued I/O System 

RT-ll performs I/O transfers thirough a queued I/O system. A job can thus 
have multiple I/O requests outstanding at a given time — that is, it can 
issue an I/O request and still continue processing. 

RT-ll implements queued I/O through the queue elements, the device 
handlers, and the routines in the Resident Monitor. Once a device handler is 
in memory and the job has opened a channel, any .READ or .WRITE re- 
quests for the corresponding peripheral device are interpreted by the 
monitor and translated into a call to the handler. Figure 3-6 illustrates the 
relationship between these components. 
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Figure 3-6: Components of the Queued I/O System 
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3.3.1 I/O Queue 

The RT-11 I/O queue system consists of a Unked list of queue elements for 
each resident device handler and a queue of available elements for each job. 
I/O queue elements are seven words long for SJ and FB systems, and 10 
decimal words long for XM systems. RT-11 provides one queue element in 
the Resident Monitor for the SJ environment. For the FB and XM en- 
vironments, each job has one queue element in its impure area. One queue 
element is sufficient for a job that uses wait-mode I/O. 

Figure 3-7 shows the format of an I/O queue element. It includes the sym- 
bolic names and offsets, as well as the contents of each word in the data 
structure. 

If your program uses asynchronous I/O, you must allocate more queue 
elements for it by using the .QSET programmed request. Otherwise, if the 
program initiates an I/O transfer and no queue element is available, RT-11 
must wait for a free element before it can queue up the new request. Ob- 
viously, this slows processing. The number of queue elements is always suf- 
ficient when you allocate n new elements, where n is the total number of 
pending requests that can be outstanding at one time for a particular pro- 
gram. This produces a total of n H- i available elements, since the original 
single queue element is added to the list of available elements. 
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Figure 3-7: I/O Queue Element Format 



NAME 


OFFSET 


CONTENTS 


CLINK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 


Q.CSW 


2 


POINTER TO CHANNEL STATUS WORD IN I/O 
CHANNEL (SEE FIGURE 3-29) 


Q.BLKN 


4 


PHYSICAL BLOCK NUMBER 


Q.FUNC 
Q.UNIT 
Q.JNUM 


6 

7 

7 


RESERVED 
(1 BUT) 


JOB 

NUMBER 
(4 BITS) 
0= BG 


DEVICE 
UNIT 
(3 BITS) 


SPECIAL 
FUNCTION 
CODE 
(8 BITS) 


Q.BUFF 


10 


USER BUFFER ADDRESS (MAPPED THROUGH PARI 
WITH Q.PAR VALUE, IF XM) 


Q.WCNT 


12 


(if <0, OPERATION IS WRITE 
WORD COUNT <(lF=0, OPERATION IS SEEK 

(if >0, OPERATION IS READ 
THE TRUE WORD COUNT IS THE ABSOLUTE 
VALUE OF THIS WORD. 


Q.COMP 


14 


COMPLETION (\F 0, THIS IS WAIT-MODE I/O 
ROUTINE llF 1, JUST QUEUE THE REQUEST 
CODE {and return 

/if even, completion routine 
(^address 


Q.PAR 


16 


pari value (XM ONLY) 






reserved (XMONLY) 






RESERVED (XM ONLY) 



The list header, called AVAIL,, is a linked list of free queue elements. It con- 
tains a pointer to an available queue element. If AVAIL is 0, no elements 
are currently available. Figure 3-8 shows an I/O queue with three queue 
elements, all of which are available. In this diagram, AVAIL points to ele- 
ment 1. The first word in each queue element is a pointer to the next ele- 
ment in the queue. Thus, element 1 is linked to element 2, element 2 is link- 
ed to element 3, and element 3 is the last element in the linked list; its link 
word is 0. 

When a program initiates a request for an I/O operation, the monitor 
allocates a queue element for the request by removing it from the list of 
available elements. The monitor then links the element into the I/O queue 
for the appropriate device handler. This is accompUshed by using two words 
in the handler header — ddLQE and ddCQE. 

The fourth word of the handler is a pointer to the last element in its queue. 
This pointer is called ddLQE, where dd is the two-character physical device 
name. The fifth word of the handler, called ddCQE, is a pointer to the cur- 
rent queue element. 
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Figure 3-8: I/O Queue with Three Available Elements 
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Figure 3-9 shows the status of the queue elements when one I/O request is 
pending. The monitor removes the first queue element from the available 
list and puts it on the device handler's queue. 

When a program requests a second I/O transfer for the same handler before 
the first transfer completes, the monitor removes another queue element 
from the available list and adds it to the queue for that handler. Figure 3-10 
illustrates this. 

When the transfer currently in progress completes, the monitor returns 
queue element 1 to the available list and initiates the transfer indicated by 
queue element 2. Figure 3-11 illustrates the queue status when one element 
is returned. 

When the I/O operation indicated by queue element 2 finishes, the monitor 
returns that element to the available Ust, as Figure 3-12 indicates. Note 
that the elements are now Unked in a different order from that shown 
previously in Figure 3-8. 

In SJ systems, the monitor always puts the new queue element at the end of 
the device queue. By using ddLQE it can do this quickly. In FB and XM 
systems, the device queue is sorted in order by job number, with the queue 
elements belonging to the highest job number appearing at the beginning of 
the queue and those belonging to the lowest job number at the end. The 
monitor puts the new element in the queue at the end of the list within a 
specific job group. Thus, if two requests are queued waiting for a particular 
handler, the request with the higher job number is honored first. At no time 
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though, does the monitor abort sm I/O transfer ah-eady in progress to start a 
higher priority request. The operation in progress always completes before 
the monitor initiates another transfer. 



Figure 3-9: I/O Queue with Two Available Elements 



QUEUE OF AVAILABLE ELEMENTS 
AVAIL: 



Q2: 



Q3 



Q2 



Q3: 



QUEUE FOR A DEVICE HANDLER 

LQE: Q1 
CQE: Q1 



Q1: 



Figure 3-10: I/O Queue with One Available Element 
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Figure 3-11: I/O Queue When One Element Is Returned 
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Figure 3-12: I/O Queue When Two Elements Are Returned 
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Figure 3-13 illustrates a large queue for a device handler. The monitor adds 
the new element, an I/O request from the foreground job, to the queue at 
the end of the list of other foreground job elements. Note that the monitor 
does not preempt the current queue element, even though it is a request 
from the background job. 

Figure 3-13: Device Handler Queue When a New Element Is Added 
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Q2 
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-THIS I/O TRANSFER IS CURRENTLY 
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Q3 



JOB NUMBER = 16 
(FOREGROUND JOB) 



Q3: 
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JOB NUMBER = 16 
(FOREGROUND JOB) 



Q4: 



NEW QUEUE ELEMENT 



Q5 



JOB NUMBER = 14 
(SYSTEM JOB 6) 
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JOB NUMBER = 16 
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JOB NUMBER = 12 
(SYSTEM JOB 5) 
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JOB NUMBER = 
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-THIS ELEMENT IS THE LAST ONE 
IN THE QUEUE; ITS LINK WORD 
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3.3.2 Completion Queue 

In FB and XM systems, the monitor maintains a completion queue for each 
job, using it to serialize completion routines for each job. The head of the 
completion queue is called I.CMPL and it is located at offset 6 from the 
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start of the impure area. I.CMPE, at offset 4, points to the end of the com- 
pletion queue. By using I.CMPE, the monitor can quickly add a new com- 
pletion queue element to the end of the queue. 

A completion routine is a section of code in a program that begins to ex- 
ecute as soon as an asynchronous event occurs. For example, the .RE ADC 
programmed request starts an I/O transfer and provides the address in the 
program at which execution is to begin when the I/O transfer completes. 
See the RT-11 Programmer'' s Reference Manual for a more thorough 
description of completion routines. 

When an I/O transfer completes, the monitor checks Q.COMP at offset 14 
octal from the start of the I/O queue element. If the value is greater than 1 
it specifies a completion routine address. The monitor then transforms the 
I/O queue element into a completion queue element and places it on the com- 
pletion queue for the job whose job number appeared in Q. JNUM at offset 7 
from the start of the I/O queue element. 

Figure 3-14 shows the format of a completion queue element. It includes 
the symbolic names and offsets, as well as the contents of each word in the 
data structure. 

Figure 3-14: Completion Queue Element Format 



NAME 


OFFSET 


CONTENTS 


Q.LINK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 




2 


RESERVED 




4 


RESERVED 




6 


RESERVED 


Q.BUFF 


10 


CHANNEL STATUS WORD 


Q.WCNT 


12 


OFFSET FROM START OF CHANNEL AREA TO THIS CHANNEL 


Q.COMP 


14 


COMPLETION ROUTINE ADDRESS 






THREE ADDITIONAL WORDS ARE PRESENT IN XM SYSTEMS. THEY 
ARE UNUSED, AND ARE RESERVED FOR FUTURE USE BY DIGITAL. 



3.3.2.1 SJ Considerations — The SJ monitor does not maintain a completion 
queue. As a result, completion routines in SJ are never serialized. (Whether 
or not you select timer support at system generation time does not affect 
the serialization of completion routines.) When you issue a completion-mode 
programmed request (such as .READC or .WRITC) and the I/O transfer 
completes, the monitor does not transform the I/O queue element into a 
completion queue element. Instead, it returns the element to the list of 
available queue elements. It then moves the Channel Status Word to RO 
and the channel number to Rl, and begins executing the program's comple- 
tion routine. Thus, the completion of another I/O transfer could interrupt 
the current completion routine and begin execution of another one. 

3.3.2.2 .SYNCH Considerations — The .SYNCH request also makes use of 
the completion queue in FB and XM systems but it does not use an I/O 



3-18 Resident Monitor 



queue element. When you issue a .SYNCH call, you supply as an argument 
the address of a seven-word area in your program, called the synch block. 
The synch block contains, among other things, the address of the routine to 
be executed. Figure 3-15 shows the format of a synch block, or synch queue 
element. When the monitor int<3rprets your .SYNCH request there is no cur- 
rent I/O queue element for it to modify. So, it uses your seven-word area as 
a completion queue element. The monitor puts the synch block at the head 
of the appropriate job's completion queue. 

Figure 3-15: Synch Queue Element Format 



NAME 


OFFSET 


CONTENTS 


Q.LINK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 


Q.CSW 


2 


JOB NUMBER 


Q.BLKN 


4 


RESERVED 


Q.FUNC 


6 


RESERVED 


Q.BUFF 


10 


SYNCH ID 


Q.WCNT 


12 


-1 (CUE THAT THIS IS A SYNCH ELEMENT) 


Q.COMP 


14 


SYNCH ROUTINE ADDRESS 






THREE ADDITIONAL WORDS ARE PRESENT IN XM SYSTEMS. THEY 
ARE UNUSED, AND ARE RESERVED FOR FUTURE USE BY DIGITAL. 



3.3.3 Flow of Events in I/O Processing 

As the central manager of the device-independent I/O system, the Resident 
Monitor supervises the I/O procedure, using a queue element as the com- 
munication link between a device handler and a program that requests an 
I/O transfer. The following sec tions describe the sequence of events that oc- 
cur in a simple read or write operation. 

3.3.3.1 Issuing the Request — Betore a program can request an I/O transfer, 
it has to open a new file or find an existing file on a device. This procedure 
sets up a channel containing i'ive words of information about the location 
and length of the file. A channel number is associated with the five-word 
block so that you can refer to the block later by specifying this number in a 
single byte. The monitor uses the channel information when it needs to pro- 
cess an I/O request. 

A running program initiates an I/O procedure by issuing a request to read 
from or write to a particular channel. MACRO-11 programs, for example, 
can use the .READ, .READW, .READC, .WRITE, .WRITW, .WRITC, and 

.SPFUN programmed requests. Programs written in other languages use 
similar statements to read and write data. 

When the I/O request executes, the monitor uses the channel number the re- 
quest specifies to find the corresponding device handler. Then the monitor 
calls its queue manager routine, which allocates a queue element from the 
list of available elements and fills in the necessary information. 



Resident Monitor 3-19 



When a queue element is not available in SJ systems, the monitor executes 
in a tight loop, waiting for a queue element to appear in the list of available 
elements. This condition is satisfied when a device interrupts and the 
handler issues the .DRFIN macro, which indicates that an I/O transfer is 
complete, and the monitor returns the queue element for that transfer to 
the available Ust. 

When a queue element is not available in FB and XM systems, the job re- 
quests a scheduling pass starting with the job whose priority is immedi- 
ately below that of the current job. When the original job gets a chance to 
run again, it first checks the available list for a free queue element. If no ele- 
ment is available, it requests another scheduhng pass. In FB systems, there 
is no blocking bit associated with queue element availability. Therefore, the 
job that needs a queue element is not officially blocked, even though it can- 
not run effectively until it gets a queue element. 

3.3.3.2 Queuing the Request in SJ — Once a new queue element has been 
allocated by the queue manager, the element is put on the device handler's 
queue. In an SJ system the new element always goes at the end of the 
queue. To prevent interference from a device interrupt (which might remove 
a different element from the same queue), the SJ monitor goes to priority 7 
to manipulate the queue. 

If the queue is empty, the monitor makes the new element both the current 
and the last element in the queue. It increments the count of queue 
elements on this channel (the byte at offset 10 octal in the channel area), and 
returns the priority to its previous level. It then jumps to the handler's I/O 
initiation section to start up the transfer. The handler starts the transfer 
and returns control to the monitor with an RTS PC instruction. 

If the queue is not empty, the handler is busy so the monitor puts the new 
element at the end of the queue. It increments the count of queue elements 
on this channel (the byte at offset 10 octal in the channel area), and returns 
the priority to its previous level. 

Whether or not the queue was empty, the queue manager checks to see if 
this request is for wait-mode I/O. If it is, the system executes in a tight loop 
until the transfer specified by this queue element finishes. If this request is 
not for wait-mode I/O, control returns to the program, which executes while 
I/O occurs simultaneously. 

3.3.3.3 Queuing the Request in FB and XIVI — In FB and XM systems, all jobs 
(system utility programs, application programs, and language processors) 
and the Keyboard Monitor run in user state. Each job uses its own stack. In 
user state a low-priority job that is running can be replaced by a higher- 
priority job that is runnable. Similarly, a higher-priority job that is unable 
to run for any reason can be replaced by a runnable lower-priority job. 

The FB and XM monitors switch to system state to modify important data 
structures and to perform operations that do not run entirely within a job. 
Stack operations and interrupts in system state use the monitor's stack 
rather than a job's stack. Jobs cannot run when the monitor is in system 
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state, and switching between lower- and higher-priority jobs is postponed 
until the monitor returns to user state. In system state, then, the monitor 
can safely modify critical data structures without the risk that another job 
could gain control and corruptt the same data structures. (Section 3.4.1 
describes system and user state in greater detail.) 

Because in SJ systems there is only one execution state, the terms "user 
state" and "system state" are not meaningful in those systems. 

In an FB or XM system, the monitor switches to system state before it puts 
the new element on the device handler's queue in order to prevent in- 
terference from other jobs. It does not raise the priority to 7, as does the SJ 
monitor, because this would lock out device interrupts for too long a time. 
However, a device interrupt could remove an element from the queue while 
the monitor is adding the new element and adjusting the LQE and CQE 
pointers. To ensure the integ:rity of the queue, the monitor holds the 
handler while it performs the raodification. 

Holding a handler prevents any other process or routine from changing the 
I/O queue. For example, when a device interrupts and an I/O operation com- 
pletes, the handler issues a .IDRFIN call to return to the monitor and 
remove the current queue element from the I/O queue. Depending on the 
type of I/O request the program issued, the current element should either 
go back to the linked list of available queue elements, or it should go onto 
the completion queue for the appropriate job. However, if the handler is 
held when it issues the .DRFIN, the monitor does not remove the current 
queue element from the I/O queue. Instead, it delays this action by setting a 
flag that it checks later. Similarly, when a job aborts, the abort routine 
holds a handler while it removes queue elements belonging to the aborted 
job. This prevents the monitor from starting up the next transfer queued 
for this device until all elements for the aborted job are gone. After the 
monitor holds the device handler, it checks to see if the queue is empty. 

If the queue is empty, the monitor clears the hold flag for the handler right 
away, and then makes the new element both the current and the last ele- 
ment in the queue. It increments both the count of queue elements on this 
channel (the byte at offset ICl octal in the channel area), and the total 
number of I/O requests for this job. Remaining in system state, the monitor 
jumps to the device handler's I/O initiation section to start up the transfer. 
When the handler starts the transfer and returns control with an RTS PC 
instruction, execution of the program continues in user state within the 
queue manager. That is, the monitor is executing "for the program". 

If the queue is not empty, the raonitor continues to hold the handler until it 
finishes modifying the queue. Elements in the queue are sorted by job 
number, as Section 3.3.1 explains. The monitor searches the queue from 
front to back, and places the: new element at the end of the group of 
elements belonging to this job. It increments both the count of queue 
elements on this channel (the byte at offset 10 octal in the channel area), and 
the total number of I/O requests for this job. Since the device handler is 
busy, the monitor cannot start up an I/O transfer for this request, so its 
queue element sits in the queue. The queue manager returns to user state. 
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Whether or not the queue was empty, the queue manager checks to see if 
this request is for wait-mode I/O. If so, the program waits for the transfer to 
complete. If this request is not for wait-mode I/O, execution of the program 
continues concurrently with the I/O transfer. 

3.3.3.4 Performing the I/O Transfer — After the monitor and a device handler 
have started up an I/O transfer, a peripheral device performs the actual 
operation and interrupts when it is finished. The interrupt causes control to 
pass to the device handler's interrupt service section, where the code 
assesses the results of the I/O operation and restarts it if necessary. When 
the transfer is done, the handler uses the .DRFIN macro to return to the 
monitor and remove the current queue element from its I/O queue. 

Figure 3-16 summarizes the relationship between the parts of a device 
handler and the Resident Monitor. Chapter 7 provides a detailed descrip- 
tion of the internal operation of a device handler. 



Figure 3-16: Device Handler/Resident Monitor Relationship 
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3.3.3.5 Completing the I/O Request — When a device interrupts, an I/O 
transfer completes, and the handler issues the .DRFIN call, it is the 
monitor that must take the appropriate action to complete the I/O pro- 
cedure. In general, this means that the monitor must remove the current 
queue element from the handler's I/O queue and put it in the list of available 
elements or on the completion queue. In an FB or XM system, another I/O 
request could cause the monitor to hold the handler while it adds an element 
to the queue. In this case, the monitor simply sets a flag, dismisses the in- 
terrupt, and returns to the interrupted process, removing the element later. 

In all SJ systems, and in those FB or XM systems in which the handler is 
not held, the monitor first decrements the count of queue elements on this 
channel. In an FB system, when the count reaches 0, it makes runnable a 
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job that is waiting for activity on this channel to complete. In FB and XM 
systems only, the monitor next decrements the total number of I/O re- 
quests pending for this job. Again, if this number becomes 0, it makes run- 
nable a job that is waiting for all its I/O to complete. When either count 
reaches 0, it can cause the scheduler to run. 

Next, for all systems, the monitor removes the queue element from the 
handler's queue. If there is another element in the handler's queue waiting 
to be processed, the monitor calls the handler again to start the next opera- 
tion as soon as the final disposition of the current element is resolved. The 
monitor raises the priority to 7 for a short time as it links the element into 
either the list of available elements or (except for SJ systems) the job's com- 
pletion queue. In FB, if the element specifies a completion routine address 
at offset 14 octal, the monitor transforms the I/O queue element into a com- 
pletion queue element and puts it at the end of the job's completion queue. 
Then the monitor returns control to the process or program that was inter- 
rupted. In SJ, if the element specifies a completion routine, the monitor 
merely returns the I/O queue element to the list of available elements. Then 
it puts the Channel Status Word in RO, puts the channel number in Rl, and 
begins immediate execution of the completion routine. 

In all SJ systems, and in theses FB and XM systems in which the element 
does not specify a completion routine address, the monitor simply returns 
the element to the available list. Control returns to the process or program 
that was interrupted, or (except in SJ systems) the scheduler can run.. 

3.4 Scheduling in Foreground/Background Systems 

In an FB or XM system the monitor must arbitrate the demands of up to 
eight jobs for processor time, in addition to performing all its other func- 
tions. Clearly then, because of the implications of having more than one job, 
the FB and XM systems are considerably different from the SJ system. The 
FB and XM monitors use a number of special tools to implement support 
for more than one job. 

The scheduler is the part of the monitor that determines which job is eligi- 
ble to run and gives control of the processor to it. The scheduler uses a sim- 
ple algorithm to determine which job should run. It looks at the jobs in 
order from highest priority to lowest. If a job exists and is runnable, the 
monitor restores its context and returns to it. Status bits in a flag word 
(I.BLOK, at offset 36 octal from the start of the impure area) reflect the 
blocking conditions that can prevent a job from running and thereby give a 
lower-priority job a chance to execute. Context switching is the procedure 
through which the monitor saves a job's context — its machine environ- 
ment and important job-specific information — and begins execution of 
another job. 

All the processes that are job-dependent are kept separate from those that 
are monitor functions. The monitor functions are, therefore, re-entrant. 
Data structures that contain job-specific information are located in the im- 
pure area for each job, and each job has its own stack. Routines that run in 
a job-dependent environment, including some parts of the monitor, use the 
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job's stack and run as part of the user job in user state. Any routines that 
run outside a job's context, including interrupts, use the monitor's stack 
and execute in system state. This arrangement allows the monitor to "un- 
wind" the stack after a series of interrupts without changing jobs or stacks. 

Two or more jobs can share a peripheral device, so the queued I/O system 
(as Section 3.3 explains) must keep track of the priority of the job re- 
questing an I/O transfer and act accordingly. The USR is interlocked -- 
that is, it cannot be shared by two jobs; all jobs must take turns using the 
USR. 

Lastly, monitor routines check for blocking conditions, change execution 
state, interlock parts of the monitor to prevent corruption of important 
data structures, request a scheduling pass, and so on. The following sec- 
tions describe the components of FB and XM systems and provide an 
understanding of the scheduling process in a multi-job environment. 

3.4.1 User and System State 

In order to isolate job-dependent functions from monitor processes, the FB 
and XM systems provide two execution states: user state and system state. 
All jobs and the Keyboard Monitor run in user state. Each job maintains 
relevant data in its impure area, and each job uses its own stack. Context 
switching is enabled in user state. That is, a lower-priority job that is run- 
ning can be replaced by a higher-priority job that is runnable. A higher- 
priority job that is unable to run for any reason can be replaced by a run- 
nable lower-priority job. 

The monitor switches to system state and the system stack for several 
reasons. Jobs cannot run when the monitor is in system state, and context 
switching is delayed until the monitor returns to user state. Consequently, 
the monitor can modify important data structures in system state without 
interference from other jobs. The monitor uses system state for operations 
that do not run entirely within a job context. These operations, which must 
not be interrupted by context switching, include the following: 

• Blocking a job 

• Starting up an I/O transfer 

• Aborting an I/O transfer 

• Servicing a timer request 

• Executing the .PROTECT programmed request 

• Executing the .CHCOPY programmed request 

• Interlocking the USR 

• Executing any XM mapping programmed request 

• Servicing an interrupt 

• Executing device handler code (except for .TIMIO completion routines 
and .SYNCH routines, which run in user state in a specific job's 
context) 
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Because it is chiefly system oir monitor routines that execute in system 
state, monitor errors are fatal. Traps to 4 (odd address errors, and illegal or 
nonexistent memory addressing errors) and traps to 10 (illegal or reserved 
instruction errors) occurring in system state halt the system. 

3.4.1.1 Switching to System State Asynchronously — The monitor switches 
from user state to system state asynchronously whenever an interrupt oc- 
curs. As a result of the interru]3t the monitor may modify important data 
structures. The switch to system state prevents interference from a context 
switch while the modifications are in progress. In FB the monitor switches 
from the job's stack to the system stack. In XM the monitor does not per- 
form the stack switch because the hardware does it automatically. Subse- 
quent interrupts that occur in system state put information on the system 
stack. Note that these subsequent interrupts do not cause another switch 
to system state. 

Interrupt Level Counter 

The monitor recognizes three levels of execution state. It uses a counter 
called INTLVL to distinguish among the three levels. Every interrupt in- 
crements this counter. When INTLVL is — 1, execution is in user state. 
When INTLVL is 0, execution is in system state at level zero. When 
INTLVL is positive, execution is still in system state, but at a deeper inter- 
rupt level. Table 3-2 summarizes the relationship between the number of in- 
terrupts pending and the execution state. 

Table 3-2: Values of the Interrupt Level Counter (INTLVL) 

Number of Interrupts Value of INTLVL Execution State 

- 1 User State 

1 System State Level Zero 
2 or more 1 or greater Deeper System State 

Figure 3-17 shows how interruf>ts influence the flow of events in a running 
system. 

$INTEN Monitor Routine 

When an interrupt occurs, control passes to the routine specified in the in- 
terrupt vector, and the current PS and PC are put on the job's stack. In 
RT-11, both device handlers and in-line interrupt service routines call the 
monitor at the common interrupt entry point, $INTEN. Device handlers 
use the .DRAST macro to call the monitor; in-line interrupt service routines 
use the .INTEN macro. 

$INTEN is the monitor routines that performs the switch to system state. 
The routine assumes that it was called because an interrupt occurred. 
Therefore, it expects the old PS and PC to be on the job's stack. The priori- 
ty should be 7, and the interru]Dt service routine must not have destroyed 
any registers between the time the interrupt occurred and the time 
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$INTEN was called. Device handlers generally caU the monitor immedi- 
ately, before they do any processing at all. In-line interrupt service routines 
sometimes perform crucial operations immediately, at priority 7, then call 
$INTEN to lower processor priority to device priority. 

Figure 3-17: Interrupts and Execution States 
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$INTEN assumes it was called with the following instruction sequence, or 
its equivalent: 

JSR R5,@$INTEN 

.WORD '"C< priority MO >&340 

$INTEN's first action is to save R4 on the job's stack. Since the JSR 
instruction already saved R5, the job's stack now appears as shown in 
Table 3-3. 



Table 3-3: Job's Stack after $INTEN 

Byte Offset Contents 



Agent 




2 
4 
6 



R4 


IINTEN 


R5 


.DRAST macro (JSR R5) 


PC 


interrupt 


PS 


interrupt 
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Next, $INTEN increments the INTLVL counter from - 1 to 0. It saves the 
job's stack pointer in a memorj/^ location and switches to the system stack. 
$INTEN then lowers processor priority to device priority, and calls the 
device handler or interrupt serdce routine back as a co-routine. The inter- 
rupt service routine continues to execute in system state. 

3.4.1.2 Switching to System State Synchronously — The monitor .switches to 
system state sychronously — that is, without depending on an interrupt — 
whenever other monitor routimss need to go to system state temporarily to 
ensure the integrity of a certain operation. In these circumstances, the 
monitor routines can call the $ENSYS routine to switch to system state. 

In special circumstances, a routine in a running job (rather than in the 
monitor) needs to switch to system state. The routine can do this by 
artificially mimicking an internipt and using the .INTEN macro to call the 
$INTEN monitor routine. 

$ENSYS Monitor Routine 

The $ENSYS routine is voluntarily and synchronously called by any other 
monitor routine that needs to switch to system state. $ENSYS mimics an 
interi-upt by altering the job's stack so it duplicates the stack condition im- 
mediately after an interrupt. Routines call $ENSYS by using the following 
instnictions: 



JSR 


R5,$ENSYS 


.WORD 


< ret urn address>- 


.WORD 


340 



The instructions following the call to $ENSYS execute m system state. 
When the routine that must execute in system state completes, it issues an 
RTS PC instruction. Control then passes in user state to the routine 
specified in the calling sequence as < return address>. 

Table 3-4 shows how $ENSYS manipulates the stack to imitate an 
interrupt. 



Table 3-4: Job's Stack after $ENSYS 

Byte Offset Contents 



R5 

2 return address 

4 



.INTEN Macro 

When a routine in a user job neieds to switch to system state, it can use a 
procedure similar to $ENSYS, which is used solely by monitor routines. 
Essentially, the routine must push the PS and PC onto the stack, and then 
call the monitor $INTEN routine with a JSR R5 instruction, which puts R5 
on the stack as well. 
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A device handler or a user program subroutine can use the following in- 
structions to switch to system state: 



MOV @SP,-(SP) 

CLR 2(SP) 

.MIPS #340 

.INTEN 0,PIC 



MAKE ROOM ON THE STACK 
FAKE INTERRUPT PS = 
GO TO PRIORITY 7 
ENTER SYSTEM STATE 



This routine must be executed with a return address on the top of the stack, 

3.4.1.3 Returning to User State — Any routine that is executing in system 
state issues an RTS PC instruction when it completes. The monitor "un- 
winds" its stack from one or more interrupts as each RTS PC instruction is 
issued. As each routine completes, the monitor decrements the INTLVL 
counter. 

When INTLVL is greater than 0, it indicates that the routine that was just 
interrupted was executing in system state. The monitor defers some special 
chores until it is just about to return to user state. If it is time to decrement 
INTLVL after an RTS PC instruction, and the value of INTLVL is current- 
ly 0, the monitor knows that it is about to drop back to user state. At this 
time, there are four special considerations for the monitor: 

• Is there an outstanding fork routine? (Fork routines run before jobs or 
their completion routines.) 

• Is a scheduling pass required? (As a result of an interrupt, a job that 
was previously blocked may now be runnable.) 

• Are there outstanding clock ticks? (The monitor may need to normalize 
its time of day counter and check the timer queue.) 

• Is there an outstanding floating-point interrupt? 

After taking these considerations into account, the monitor is ready to 
return to user state. It decrements INTLVL to - 1 and switches to the ap- 
propriate job's stack. It restores R4 and R5, and then executes the RTI in- 
struction to begin execution in user state. 



3.4.2 Context Switching 

Context switching occurs as a result of the scheduler's command to run a 
different job. Its purpose is to restore the context for a job so that it can 
run. Context switching can occur for one of two reasons: 

• The current job becomes blocked and a lower-priority job is runnable. 

• A higher-priority job than the current job becomes runnable. 

Note that the RT-11 monitor never saves a job's context simply because it 
switches to system state. For example, if there is only one job running, the 
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monitor does not bother to save or restore its context. A job's context is 
only significant when there are two or more jobs running. Many other 
multi-user operating systems switch out the user job every time they leave 
user state and enter system state. RT-11 avoids the overhead of un- 
necessary context switching by saving and restoring the context only when 
it runs a different job. This is a significant saving because there are many 
situations in which a job is ininning, an interrupt triggers a switch to 
system state, and control passes back to the same job once the interrupt is 
serviced. 

When the monitor saves a job's context, it saves the job-dependent infor- 
mation on the job's stack and in the job's impure area. The following infor- 
mation is saved in a context switch: 

PS 

PC 

Stack Pointer (saved in the impure area) 

Registers RO through R5 

Kernel PARI (XM only) 

Memory management fault trap vector (XM only) 

BPT vector (XM only) 

lOT vector (XM only) 

TRAP vector 

System communication area (locations 40-52) 

Location 56 (multi-terminal systems only) 

FPP status word and floating-point registers (if floating-point hard- 
ware present) 

All data specified by the program in a .CNTXSW programmed request 

Stack and impure area (which are, of course, part of the job) 

When the monitor switches in the new job's context, it tests for a pending 
completion routine by checking a status bit in I.STATE. If the job's com- 
pletion queue has a completion queue element on it, the monitor puts a 
pseudo-interrupt on the job's stack to call the completion queue manager 
when the scheduler actually stsirts up the job. 

3.4.3 Blocking Conditions 

A running job is blocked if it carmot proceed until some asynchronous event 
happens. Table 3-5 lists the blocking conditions, the bits in I.BLOK (at im- 
pure area fixed offset 36 octal) that reflect the conditions, and the events 
that imblock a job. Unused bits are reserved for future use by DIGITAL. 
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Table 3-5: Blocking Conditions 



Blocking Agent 



I.BLOK Bit, 

Name, and 

Mask 



Unblocking Agent 



Any request that uses the 
USR; any monitor command; 
an exit from a background job. 

The keyboard monitor 
SUSPEND command. 



The .EXIT request; a job 
that aborts 



Termination of the foreground 
or system job. 

The .SPND or the .TWAIT 
programmed request. 



The .READW, .WRITW, 
.WAIT, .SDATW, .RCVDW, 
.MWAIT programmed 
requests. 

The .EXIT programmed 
request issued from a 
foreground or system job; 
the .MTSET request issued for 
a DZ line; .MTDTCH issued 
for any terminal but a shared 
console. 

The .TTYOUT, .PRINT, 
.MTOUT, and .MTPRNT 
programmed requests. 

The .TTYIN request (with 
JSW bit 6 clear); the .CSIGEN, 
.MTIN, .CSISPC, and .GTLIN 
programmed requests. 

Any request that needs a 
queue element when none is 
available. 



4 The USR release routine, DEQUSR, 

USRWT$ when the USR is free and no 

20 higher-priority job needs it. 

6 The Keyboard Monitor, when an 

KSPND$ operator types the RESUME 

100 command. 

8 I/O completion from device 
EXIT$ handlers, when the job's total I/O 
400 count is 0. 

9 None. Only the Keyboard Monitor 
NORUN$ can clear this bit by removing 
1000 the job image from memory. 

10 The monitor's .RSUM processor, 
SPND$ when the .RSUM request executes 
2000 or a .TWAIT completion routine 

runs. 

11 I/O completion from device 
CHNWT$ handlers, when the I/O count for 
4000 the specified channel is 0. 

12 The monitor's terminal service 
TTOEM$ output routine, when the output 
10000 ring buffer is empty or CTRL/0 is 

typed. 



13 The monitor's terminal output 
TTOWT$ interrupt service routine, when 
20000 there is room in the output 

ring buffer. 

14 The monitor's terminal input 
TTIWT$ interrupt service routine, when 
40000 a line or character is available. 

none The monitor's queue element 

return routine, when a queue 
element becomes free. 



Note that there is no bit that indicates that a job is waiting for a queue ele- 
ment. This is a special case and the monitor handles it by checking the list 
of available queue elements. If there are none, it requests a scheduling pass 
to give a lower-priority job a chance to run. The monitor continues to check 
the available list until a queue element becomes available. 
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3.4.3.1 How the Monitor Blocks a Job — A job becomes blocked when it en- 
counters any of the circumstances listed in Table 3-5. These circumstances 
are brought about when one of the three following events occurs: 

• The job issues one of the programmed requests listed in Table 3-5. 

• The monitor SUSPEND c;ommand is typed. 

• The job aborts. 

Typically the job, which is running in user state, issues a programmed re- 
quest, such as .EXIT. The monitor remains in user state while it processes 
the programmed request. It then checks to see if the job is waiting because 
of a blocking condition. The .EXIT request, for example, must wait for all 
the job's I/O requests to complete before it actually terminates the job. 
Since waiting for all I/O to comiplete is a blocking condition, the monitor in- 
itiates the appropriate test to see if there are outstanding I/O requests and 
this job is now blocked. 

The monitor calls its $SYSWT routine whenever it needs to determine 
whether or not a job is blocked. The monitor passes to $SYSWT a bit mask 
for the bit in I.BLOK corresponding to this particular condition. (Table 3-5 
lists the bit masks for I.BLOK; bit 8 corresponds to the .EXIT request con- 
dition.) It also passes a decision subroutine, which is a routine that deter- 
mines whether or not a job is blocked for a particular reason. There is a 
unique decision subroutine for each call to $SYSWT, except the waiting for 
a queue element condition, whi(;h has none. The decision subroutine returns 
with the carry bit set if the job is indeed blocked. Note that a job can be 
blocked for only one reason at a time. 

When control eventually returns to the job, it executes within the monitor 
in user state at $SYSWT again. (That is, the monitor runs under the 
auspices of the job, executing code on its behalf.) The blocking condition 
must be checked once more in order to reblock a job that may have been 
unblocked to allow a completion routine to run. (Completion routines are 
part of a job, but they can run even if the main part of the job is blocked. 
The monitor unblocks the job to run the completion routine, then runs 
$SYSWT to reblock the job when the completion routine finishes. Section 
3.4.5 discusses the implications of completion routines for scheduhng.) 

3.4.3.2 $SYSWT Monitor Routino — $SYSWT is the monitor routine that 
decides whether or not a job is blocked. If a job is blocked, $SYSWT sets 
the appropriate blocking bit. The flowchart in Figure 3-18 shows how 
$SYSWT works. 

First, $SYSWT runs the decision subroutine passed by the monitor to 
determine whether or not the job is blocked for a specific reason (point yl in 
Figure 3-18). If the job is not blocked, control returns to the job and it con- 
tinues to run (point B). In the .EXIT case, for example, a job is not blocked 
if there is no pending I/O to delay the exit procedure. 

If the job is blocked, $SYSWT caUs $ENSYS to enter system state (point 
C). Then it sets the appropriate blocking bit. In the .EXIT example, a job is 
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Figure 3-18: $SYSWT Monitor Routine 
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blocked if there are pending I/O requests; $SYSWT sets the EXITS bit, bit 
8, in I.BLOK. 

Next, $SYSWT runs the decision subroutine again. If the job is stm block- 
ed, $SYSWT requests a scheduler pass (point E). It does this to give a run- 
nable lower-priority job a chance to execute. 
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If the job is no longer blocked, $SYSWT clears the blocking bit and returns 
(point E). When the monitor switches back to user state, the scheduler runs 
if a scheduUng pass is pending. When control finally returns to this job (the 
one for which $SYSWT originally ran), the monitor continues execution on 
the job's behalf at the beginning of the $SYSWT routine (point A). 

$SYSWT runs the decision subroutine twice because interrupts can occur 
while $SYSWT is running. Since an interrupt can signal the removal of a 
blocking condition, the job's status can change even as $SYSWT is trying 
to determine it. 

An interrupt can occur after the decision subroutine (point A) declares a job 
to be blocked, but before $SYS^)VT sets the blocking bit. This time interval 
is shown as "Window 1" in Figure 3-18. In this situation $SYSWT sets the 
blocking bit erroneously. But, when it runs the decision subroutine the sec- 
ond time, it discovers that the job is not blocked anymore. $SYSWT clears 
the bit and returns to the job (point E). 

"Window 2" in Figure 3-18 indicates the second time interval in which an 
interrupt can occur. The interrupt can remove the blocking condition im- 
mediately after $SYSWT correctly sets the blocking bit. In this case, the 
monitor's UNBLOK routine clears the blocking bit and requests a schedul- 
ing pass because this job became runnable. Control returns to $SYSWT 
(point D), which runs the decision subroutine again. Since the job is no 
longer blocked, execution leaves $SYSWT (point E) and the scheduler runs 
immediately before the monitor returns to user state. 

3.4.3.3 How the Monitor Unblocks a Job — An asynchronous event initiates 
the monitor's procedure to unblock a job. Table 3-5 lists the significant 
events that can unblock a job. The completion of all I/O for a specific chan- 
nel is a significant event, for example, and unblocks a job whose CHNWT$ 
bit is set. 

When an interrupt occurs, control passes to an interrupt service routine. 
The interrupt routine enters system state by executing the $INTEN 
monitor routine. Then the interrupt service routine assesses the meaning of 
the interrupt and takes appropriate action. In a device handler, for example, 
an interrupt can indicate that an I/O transfer is complete. The handler 
returns to the monitor to remove the current element from the I/O queue. 

In all cases, the monitor clears the blocking bit and requests a scheduling 
pass if the significant event removes a blocking condition. 



3.4.4 Scheduler Operations 

The scheduler runs only if thert; is an outstanding request for a scheduling 
pass. The monitor checks a flag byte called INTACT each time it is ready to 
switch from system to user st;ate. If INTACT is not equal to zero, the 
scheduler runs. 

3.4.4.1 How the Monitor Requests a Scheduling Pass — The monitor requests 
a scheduling pass by calling the $RQTSW monitor routine. It does this 
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whenever a job's ability to run changes. (That is, whenever a running job 
becomes blocked, or whenever a blocked job becomes runnable.) 

3.4.4.2 Characteristics of a Runnable Job — A job that does not have any 
blocking bit set is runnable. However, there is one circumstance in which a 
job with a blocking bit set can still be runnable. A job's completion routine 
can run even though the mainline program is blocked. Section 3.4.5 
discusses scheduling implications for completion routines. 

3.4.4.3 $RQTSW IMonltor Routine — The $RQTSW routine posts a request for 
a scheduling pass for a specific job by placing a value in the flag byte, IN- 
TACT. INTACT holds the job number of the highest-priority job that re- 
quested a scheduUng pass. $RQTSW ignores a scheduling request for a job 
if its priority is lower than that of the running job. When a job whose priori- 
ty is higher than that of the running job requests a scheduling pass, 
$RQTSW saves the job's number in INTACT, which holds the number in 
the following format: 

INTACT = Job number ^ goo 

3.4.4.4 How tlie Sclieduier Worlts — The scheduler runs just before the 
monitor returns to a job. Remember that INTLVL, the interrupt level 
counter, is when it is time to return to user state. 

A scheduling pass needed to make a job runnable happens asynchronously, 
as a result of an interrupt that removed a blocking condition. A scheduling 
pass needed to make the current job non-runnable happens synchronously, 
after a job issues a programmed request, after the monitor SUSPEND com- 
mand is typed, or after a job aborts. 

The scheduler runs only if INTACT is not equal to 0. When INTACT is 0, it 
indicates that no job changed its status, and, therefore, the same job that 
was interrupted should run again. When INTACT is not 0, it contains the 
number of the highest-priority job that changed its status. The scheduler 
runs only if the job number in INTACT is greater than the current number 
of the current job, which is kept in JOBNUM in the monitor. 

The scheduler examines jobs in order of descending priority. It starts with 
the job whose number is in INTACT, which is not necessarily the highest- 
priority job in the system. As soon as the scheduler finds a runnable job, 
the monitor switches context and runs the job. If no jobs at all are runnable, 
the system idles — that is, it runs the null job briefly, then scans all jobs 
again for runnabihty. 



3.4.5 Implications for Completion Routines 

A job's completion routine can run even though the mainline program is 
blocked. When an asynchronous event occurs, such as the completion of an 
I/O request, the interrupt service routine enters system state through the 
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SINTEN monitor routine. The device handler's interrupt service routine 
returns to the monitor when I/O completes, so the monitor can remove the 
I/O queue element from the device handler's queue. If the I/O request 
specified a completion routine address, the monitor changes the I/O queue 
element into a completion queue element and puts it on the job's completion 
queue. The monitor sets bit 7 in the job state word (I, ST ATE, the first word 
in tlbe job's impure area) to indicate that a completion routine is pending. 

As the monitor switches from system to user state, it checks the completion 
pending bit in I.STATE in the job's impure area. If a routine that just ran 
in system state queued one or more completion routines for this job and the 
job is not currently running a completion routine, the monitor clears the 
blocking bit so the scheduler can run the job. This action permits comple- 
tion routines to execute even though the mainline program is blocked. 

When all the completion routines finish, the mainline program begins to ex- 
ecute. However, since it was recently blocked, the monitor executes for the 
job at the start of the $SYSV7T routine. $SYSWT runs the relevant deci- 
sion subroutine (the routine for the condition that originally blocked this 
job) and reblocks the job, if necessary. 



3.5 System Jobs 



Through the system generation process you can create an FB or XM 
monitor that is capable of running up to six simultaneous jobs in addition 
to a foreground job and a background job. RT-11 offers the system job 
feature in order to make two valuable system jobs available: the error log- 
ger, called EL, and the file queuing program, called QUEUE. You can run 
either system j ob as the foregi'ound j ob in an RT-1 1 FB or XM system that 
does not have the system jobs feature. 

Keep in mind that even though RT-11 permits up to eight jobs to run 
simultaneously, this feature does not mean that RT-11 is a "multi-user" or 
"multi-tasking" system in any sense of the terms. The system jobs RT-11 
provides are designed to monitor hardware reliability and to write files to 
peripheral devices through a queue mechanism. Both jobs are in keeping 
with the philosophy that RT-11 is essentially a single-user system, and 
RT-11 still provides no protection for one job from another, or for the 
operating system software from any job. In the few cases where RT-11 ap- 
pears to support multiple users, a single application program or language 
processor that supports multiple terminals is actually running. In Multi- 
User BASIC-11, for example, the BASIC-11 interpreter is the single user, 
and it alone is responsible for preserving the integrity of each 
programmer's work space. 

The Resident Monitor in a system job environment is approximately 300 
decimal words larger than an equivalent monitor that does not support 
syst;em jobs. DIGITAL does not encourage customers to write theii: own 
system jobs; it reserves the reitnaining four potential system jobs for future 
use. 
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3.5.1 Characteristics 

System jobs are similar to ordinary foreground jobs in that, for both kinds 
of jobs, object code must be stored in relocatable object file format. In addi- 
tion, system jobs are subject to the same restrictions as foreground jobs — 
that is, they use restricted arithmetic with global variables. 

One difference between system and foreground jobs is that the default file 
type for a system job is .SYS, not .REL. To Link a system job, use the 
following command line format: 

LINK/FOREGROUND/EXECUTE:dev:filnam.SYS dev:filnam.OBJ 

Remember to use /EXECUTE to explicitly include the .SYS file type for the 
resulting executable module and override the default .REL file type that 
/FOREGROUND produces. 



3.5.2 Logicai Names 

You reference a system job by its logical name, which, by default, is its file 
name. However, you can assign a new name when you start the job by using 
the SRUN monitor command with the /NAME:logical-job-name option. 
Logical job names must be unique. 

The foreground and background jobs have default logical names as well as 
their actual file names. For the foreground, the default logical name is F; for 
the background, it is B. F and B are permanently assigned; you cannot use 
them for system jobs. In addition, EL is the logical job name permanently 
assigned to the error logger system job. You can assign another logical 
name to the foreground job, in addition to F by using the FRUN monitor 
command with the /NAME:logical-job-name option. 

The job name is stored in ASCII at offset I.LNAM in the job's impure area. 

3.5.3 Job Number 

In an FB or XM system without the system job feature the background job 
number is and the foreground job number is 2. In an environment that 
supports system jobs, the background job number is still 0, but the fore- 
ground job number is always 16 octal. By default, each system job takes 
the next highest available job number. Job numbers are multiples of 2, and 
range from to 16 octal. For example, the first system job you start with 
the SRUN command has a job number of 14, the second system job has a 
job number of 12, and so on. 

3.5.4 Priority 

A monitor that supports the system job feature provides the same event- 
driven, static priority scheduler that ordinary FB and XM systems use. The 
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monitor services jobs according to their priority. The background job 
always has priority 0, the lowest priority. The foreground job always has 
the highest priority, which is 7. You cannot change these assignments. 

To assign a priority to a syst(;m job you can: 

1. Use the SRUN command to start the jobs in order of their importance 
so that the first job you st;art gets priority 6, the second job gets priori- 
ty 5, and so on. 

2. Explicitly specify the priority when you start the system job. Use the 
SRUN/LE VEL:priority command to do this. You can specify a priority 
level for each job in the range 1 through 6, as long as another job is not 
currently assigned to the level you choose. 

The job number is equal to the priority times 2. 

NOTE 

You can assign a priority only when you start a system job 
with the SRUN command. The priority levels do not 
change dynamically, and you cannot change the priority of 
a job while it is running. 



3.5.!) Design Considerations 

If you are planning to write or run system jobs, you should keep in mind 
two major design considerations: 

1. RT-11 provides an event- driven, static priority scheduler. 

2. Addressing space is at a premium in an RT-11 environment, and cer- 
tain parts of each job must reside in low (rather than extended) 
memory. 

3.5.5,1 Scheduling Considerations — The RT-11 scheduler arbitrates the 
demands jobs make for CPU tiime, awarding the use of system resources to 
the highest-priority job that is not blocked. Thus, a compute-bound job can 
lock out all the jobs with a lower priority. On the other hand, an I/0-bound 
job, such as the RT-11 QUEUE program, is often blocked waiting for I/O 
transfers to complete. As a result, it does not interfere significantly with 
lower priority jobs. If you are running a text editor in the background, for 
exaraple, the fact that the QUEUE program is active is practically 
transparent to you. 

When you design a program to run as a system job, then, consider carefully 
how often it will require system resources. Keep in mind, too, the fact that 
RT-11 does not permit parallel use of the USR by two or more jobs. Write 
the program in such a way that it does not monopoUze the system and lock 
out other jobs. 
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3.5.5.2 Space Considerations -- In an FB system, the main concern is that 
the number and size of jobs is limited by the amount of space available. As 
Chapter 2 explains, KMON and the USR slide down in memory each time 
you load a foreground job, a device handler, or a system job above them. 
However, KMON cannot slide below location 1000 octal. Since the FB 
monitor and KMON are about 4K words in size each, this leaves about 20K 
words of memory for foreground jobs, device handlers, and system jobs. 
Each job carries a fixed overhead of roughly 220 decimal words for the im- 
pure area and channel space. 

XM systems have more restrictions that apply to foreground and system 
jobs. First, the USR is always resident in XM. In addition, the USR cannot 
slide down in memory into the area mapped by kernel PARI (addresses 
20000 through 40000). That is, the USR must not slide below location 40000 
in low memory. As a result of these two restrictions, about IIK words of 
memory are available for foreground jobs, device handlers, and system jobs 
in an XM environment. Each job carries a fixed overhead of approximately 
340 decimal words for the impure area and channel space. 

However, the XM environment provides other means to load and execute 
jobs. The only parts of foreground and system jobs that must reside in low 
memory are the impure area, queue elements, channels, and interrupt ser- 
vice routines. (Like the USR, these four parts of a job cannot reside in the 
PARI area.) The XM system provides three ways to make use of extended 
memory (memory above the 28K-word boundary) for foreground and 
system jobs: 

1. Use the XM .SETTOP feature in your program. 

2. Segment your program and use the /V linker option to make the 
overlays resident in extended memory. 

3. Use the memory management programmed requests in a MACRO pro- 
gram to increase the program's physical address space. 

These methods provide the means to circumvent the XM restrictions and 
execute code in extended memory. They are described in detail in Chapter 4. 

3.5.6 Programmed Requests 

Two programmed requests — .GTJB and .CHCOPY — have optional argu- 
ments that are meaningful only in an FB or XM environment with the 
system job feature. The .GTJB request obtains job status information for 
any job in the system. You can reference another job by either logical job 
name or job number. The .CHCOPY request opens a channel for input, 
logically connecting it to a file that is currently open for another job for in- 
put or output. See the RT-11 Programmer'' s Reference Manual for a detail- 
ed explanation of these requests, 

3.5.7 Message Handling 

In addition to the .SDAT/.RCVD/.MWAIT system through which fore- 
ground and background jobs communicate with each other, RT-11 pro- 
vides an easy way for all jobs, including system jobs, to send and receive 
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messages. The new message handling system is implemented through the 
message queue, or MQ, handler. This handler is a part of the Resident Moni- 
tor for all FB and XM systems, whether or not they include the system job 
feature. The MQ handler is written as a standard RT-11 device handler for a 
"special" device. This means that the pseudo-device has a non-RT-U for- 
mat. The MQ handler does not accept .SPFUN calls. One advantage of using 
a device handler in the message system is that you can still debug the send/re- 
ceive mechanism if one of the jobs involved in the system is not in memory. 

For most other purposes, the MQ handler performs like the other RT-11 
device handlers. Essentially, it makes another job appear to be a peripheral 
device. As a result, you can open a channel to any other job by using the 
.LOOKUP programmed request. You can send a message by issuing a 
.WRITW request. Then you can receive a message to the job by using a 
.READW request. The first word of the received data buffer contains a count 
of the words transferred. 

There is one significant difference between other RT-11 device handlers and 
the MQ handler, which becomes apparent when a job exits (with the .EXIT 
programmed request) or when it aborts (because of CTRL/C or a fatal monitor 
error). The monitor allows outstanding I/O requests that are queued for the 
job to complete, but discards any messages that are queued for the job by 
examining the queue for the MQ handler and removing queue elements that 
send messages to the job. 

The XM monitor normally uses a special internal macro to transfer message 
data via the MTPI instruction. This procedure is slow, but safe, since it does 
not use a PAR to map any buffers. You can use a faster, but riskier, transfer 
procedure by setting the conditional assembly symbol MQH$P2 equal to 1. 
When the MQ handler is assembled, the assembler will generate code which 
uses kernel PAR2 to map the user buffers. In this case, all the kernel PARI 
restrictions also apply to PAR2. So, the USR, queue elements, channels, and 
interrupt service routines cannot reside within locations 20000 through 60000 
in a system that actually uses the MQ handler. Note that the QUEUE pro- 
gram uses the MQ handler. 

3.5.8 Monitor Commands 

The collection of monitor commands has some special features that reflect the 
system job environment. This section describes them briefly. See Chapter 4 of 
the RT-11 System User's Guide for a complete description. 

3.5.8.1 SRUN and FRUN Commands — Use the SRUN command to start 
execution of a system job. You can also use the FRUN command to begin 
execution of a system job in the foreground partition. 

NOTE 

If you use SRUN or FRUN to start a system job and a job with 
the same name is already in memory but has finished execut- 
ing, the monitor unloads the job in memory and brings in a new 
copy from a peripheral device. 

3.5.8.2 LOAD and UN LOAD Commands — Use the LOAD command to bring a 
device handler into memory and to assign ownership of a peripheral device 
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to a specific job. Different jobs can own different units of a file-structured 
device. Since a system job must already be in memory before you can assign 
a device to it, remember to start the job with SRUN before you use the 
LOAD command. Note that you cannot assign ownership of SY or MQ. 

The UNLOAD command removes a device handler or a system job from 
memory. Be sure to type a colon (:) after the name of the device handler. 
This distinguishes it from the name of a system job. For example, RK could 
be both the name of a system job and the name of a device handler. To 
remove the device handler, type: 

UNLOAD RK: 

To unload the system job, type: 
UNLOAD RK 

3.5.8.3 SUSPEND and RESUME Commands - Use the SUSPEND command 
to stop execution of a system job. 

Use the RESUME command to continue execution of a system job that was 
stopped by the SUSPEND command or the /PAUSE option for SRUN or 
FRUN. 

3.5.8.4 SHOW JOBS Command — Use the SHOW JOBS command to display 
status information about all system jobs currently in the system. 

3.5.8.5 SET TT: NOFB Command — Use the SET TT: NOFB command to 
disable the special control keys CTRL/F, CTRL/B, and CTRL/X you use to 
communicate with foreground, background, and system jobs. 

3.5.9 Communicating with a System Job 

In a system job environment you use CTRL/X to communicate with a 
system job in much the same way that you use CTRL/F for a foreground 
job and CTRL/B for a background job. By directing input to the correct job 
and by labeling output, this mechanism permits two or more jobs to share 
one terminal. When you type CTRL/X, the monitor sends a carriage 
return/line feed combination to the terminal, followed by the Job? prompt. 
While waiting for your response, the monitor simulates a full output ring 
buffer. This prohibits output from any other job from garbling the CTRL/X 
dialogue. (This also blocks a job that is waiting for output.) 

Respond to the prompt by typing the job's logical name, followed by a line 
terminator (carriage return, line feed, or CTRL/Z). DELETE (or RUBOUT) 
and CTRL/U are valid editing commands in a CTRL/X sequence. 
Remember that F and B are reserved for the foreground and background 
jobs. If the job you specify is not running, or does not exist, the monitor 
prints a question mark (?). As a result of the CTRL/X sequence, the monitor 
directs terminal input characters to the appropriate job's input ring buffer. 

To cancel the CTRL/X sequence before you finish typing the job name, type 
CTRL/C. This does not abort any job. It simply returns to the state of the 
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terminal before you typed CTRL/X. To actually abort a system job, type 
CTRL/X followed by the job name and a line terminator. Then type two 
CTRL/Cs. 

While terminal input is directed to one job's input ring buffer, other jobs 
can still send output characters to the terminal. To avoid confusion, the 
monitor prints an identifying label every time the output user changes. The 
terminal identity string is stored at I.JID in each job's impure area and it 
consists of a carriage return/line feed combination, followed by the job 
name, a right angle bracket ( >), and another carriage return/line feed 
combination. 

The following sequence shows how two system jobs can share one terminal. 
Type a CTRL/X sequence and send a message to the first job: 

CTRL/X 

Job? SYK RET > 

HELLO TO JOB 1< RET > 

Job 2 sends a message to the terminal: 

SY2 > 

HI FROM JOB 2 

Send another message to job 1. Note that you do not type the SYl > label 
yourself. The monitor prints it when it echoes your input characters. 

SY1 > 

HELLO AGAIN TO JOB 1< RET > 

Job 2 sends two more messages: 

SY2 > 

HI AGAIN FROM JOB 2 

HI A THIRD TIME FROM JOB 2 

Finally, job 1 sends a message: 

SY1 > 

HI FROM JOB 1 



3.5.10 How to Queue Files from an Application Program 

Usually you queue files that you want to copy to another device by using 
the monitor PRINT command. If the QUEUE program is running when 
you issue the PRINT command, the files you specify are queued 
automatically and the monitor dot prints on your terminal almost 
immediately. 

Your application programs can also copy files to output devices through the 
QUEUE program. The method your program must use to do this depends 
on which monitor is currently running. If an FB or XM monitor that in- 
cludes the system job feature is running, your program must communicate 
with QUEUE through the message queue (MQ) handler by using 
.LOOKUP, .WRITW, and .READW programmed requests. Using the MQ 
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handler is beneficial because it frees the monitor for other tasks, and takes 
advantage of the existing queued I/O system. Note that the MQ handler in 
an XM system borrows kernel PAR2 for its own use; see Section 3.5.7 for 
more information on this topic. 

If an FB or XM monitor without the system job feature is running, your 
program must communicate with QUEUE through the .SDAT and .RCVD 
programmed requests. 

To queue one or more files, follow these simple steps: 

1. Set up a job block in your program for a logical group of files to be 
queued. 

2. Set up a file block for each file to be queued. 

3. Issue the .LOOKUP programmed request for the QUEUE program, 
(Omit this step if your system does not have the system job feature.) 

4. Issue the .WRITW request (or the .SDATW request if your system 
does not have the system job feature) to send the QUEUE request and 
establish a pointer to the job and file blocks. 

5. Issue the .READW request (or the .RCVDW request if your system 
does not have the system job feature) to receive acknowledgment from 
QUEUE. 

Once QUEUE acknowledges your request, your program is free to continue 
processing or to exit. Figure 3-23 shows a program that uses .LOOKUP, 
.READW, and .WRITW to queue one file, then exits. 

3.5.10.1 Setting Up the Job Block — Set up a job block in memory for a logical 
group of files. The job block defines the logical name by which you can later 
reference the entire group of files. 

If you copy files to a file-structured device (rather than to the line printer, 
for example) all the files belonging to the job are concatenated and stored in 
a file called "jobname" with the file type .JOB. The handler for the device to 
which you send the job must be made resident in memory through the 
monitor LOAD command. Figure 3-19 shows the format of the job block. 

Figure 3-19: Job Block 



FLAGBITS+FLGJR 



#0F BANNERS 



#0F COPIES 



OUTPUT DEVICE (RADIX-50) 



SIX-CHARACTER JOB NAME 
(TWO RADIX-50 WORDS) 



#0F FILE BLOCKS FOLLOWING 
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The flag word in each job block defines the action QUEUE should take on 
each file. Table 3-6 lists the definitions of the bits. Bits 4 through 15 are 
reserved for DIGITAL. 

The job block must have bit FLG.JR set. If FLG.CP is set, QUEUE sets 
the default number of copies to queue for this job from the low byte of the 
second word in the job block. If FLG.HD is set, QUEUE sets the number of 
banners to queue for this job from the high byte of the second word in the 
job block. 



Table 3-6: Request Flag Bits 

Bit Name Mask 




1 

2 

3 



FLG.DE 
FLG.CP 

FLG.HD 

FLG.JR 



1 
2 

4 

10 



Meaning 



Delete file after copying it. 

Make multiple copies (get number of copies 
from second word in block). 

Create banner pages (get number of pages 
from second word in block). 

For initial request and job block. 



3.5.10.2 Setting Up the File Block — Immediately after the job block, your 
program must set up a file block for each file that is part of the job. Arrange 
the blocks contiguously in memory, with the job block first. Figure 3-20 
shows the format of the file block. 

Figure 3-20: File Block 



FLAG WORD 



#OFBANNIERS 



#0F COPIES 



FOUR RADIX-50 WORDS 
CONTAINING DEVICE, FILE 
NAME, AND FILE TYPE OF THE 
FILE TO BE QUEUED 



In each file block you can specify the number of banner pages and the 
number of copies for the file by setting flag bits FLG.CP and FLG.HD, and 
putting values into the second word of the block. If you omit the flag bits, 
QUEUE ignores the second word of the file block and checks the flag bits of 
the job block instead. If they ares set, QUEUE takes the values from the sec- 
ond word of the file block. Finally, if the flag bits are clear in both the file 
and the job blocks, QUEUE uses the system default of no banners and one 
copy of the file, or the current default parameters as set by the QUEMAN 
/P option. 
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3.5.10.3 Setting Up the QUEUE Request Block — The last data structure you 
must establish is called the QUEUE request block. It need not be con- 
tiguous in memory with the job and file blocks. Figure 3-21 shows the for- 
mat of the QUEUE request block. This block contains the information that 
QUEUE needs to begin processing the files. 

Figure 3-21: QUEUE Request Block 



FLG.JR 



SIX-CHARACTER FILE NAME 
OF YOUR PROGRAM 
(THREE ASCII WORDS) 



ADDRESS OF JOB BLOCK 



3.5.10.4 Issuing the .LOOKUP Request — In the executable section of your 
program, you must issue a .LOOKUP programmed request to make the 
first contact with the QUEUE program and establish a communication 
channel. Issue the .LOOKUP for MQ:QUEUE, following the example pro- 
vided in Section 3.5.10.7. (Omit this step if your system does not have the 
system job feature.) 

3.5.10.5 Issuing the Request to QUEUE — If the .LOOKUP is successful (or if 
you omitted it), you next issue the .WRITW programmed request (or the 
.SDATW request if your system does not have the system job feature) to 
send your request to QUEUE. The text you send to QUEUE is the QUEUE 
request block. See the example provided in Section 3.5.10.7. 

If your request is valid, QUEUE inserts the request blocks into the queue, 
which is a workfile on device DK:. The workfile is a first-in/first-out Ust; it 
can contain requests for different output devices. QUEUE does not main- 
tain a separate workfile for each device. 

3.5.10.6 Receiving Acknowledgment from QUEUE— When QUEUE 
acknowledges your request, your program can continue execution, or exit, 
as you desire. You obtain this acknowledgment by issuing the .READW 
programmed request (or the .RCVDW request if your system does not have 
the system job feature). QUEUE'S response takes the form shown in Figure 
3-22. 

Your program must wait for this acknowledgment. QUEUE maintains only 
a limited number of extra queue elements. If QUEUE sends a message to 
your program that your program is not prepared to accept, a queue element 
is needlessly kept out of the list of available elements; this could block 
another job in your system. 
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Figure 3-22: Request Acknowledgment Block 



FLAG BITS 



SIX-CHARACTER NAME 

"QUEUE " 

(THREE ASCII WORDS) 







If the acknowledgment is positive, the flag word contains 0. If the 
acknowledgment is negative, the sign bit of the flag word is set in addition 
to one of the low three bits. Table 3-7 shows the meanings of the 
acknowledgment flag bits. 



Table 3-7: Acknowledgment Flag Bits 
Bit Name MaEik 



Meaning 






FLG.RA 





Request accepted. 


15,0 


FLG.IR 


100001 


Illegal job request. 


15,1 


FLG.QF 


100002 


Insufficient room in workfile. 


15,2 


FLG.NQ 


100004 


QUEUE being aborted from console. 



3.5.10.7 QUEUE Example Program — Figure 3-23 contains a listing of an ex- 
ample program, MYPROG, that uses QUEUE in a system with the system 
job feature to copy a data file to the line printer. 

Figure 3-23: QUEUE Example Program 



MVPROCi.MAC 


MACRO y04.00 


14-0CT-79 


18: 41! 13 PAGE 1 


1 




TITLE 


MYPROG. 


MAC 


3 
1 




THIS 
SEND 


EXAMPLE SHOWS HOW AN APPLICATION PROGRAM CA 
FILES THROUGH THE OUEUE SYSTEM. 


6 

7 

8 

9 

10 

11 

12 

13 






.ENABL 
.MCALL 


LC 

.URITU» .LOOKUPj .EXITr .PRINTi .READU 


000001 

000002 
000004 


FLAG 


BITS FOR 

FLG.DE 

FLG.CP 
FLG.HD 


REQUEST 

= 1 rllELETE FILE AFTER 

(PRINTING 
= 2 (MULTIPLE COPIES 
= 4 (BANNER PAGES 
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Figure 3-23: QUEUE Example Program (Cont.) 



15 

16 

17 

18 000000 

19 

20 

21 

22 000&00 

23 000020 

24 000022 

25 000030 

26 000032 
27 

28 000064 

29 000066 

30 000074 

31 000076 
32 

33 
34 

35 000130 

36 000132 

37 

38 000136 

39 000140 

40 000146 
41 

42 

43 000150 

44 000156 
45 

46 000000 

47 

48 

49 

50 000000 

51 000002 
000003 
000004 
000005 
000006 
000007 

53 000010 
54 



000010 



56 
57 
58 
59 
60 
61 
62 



63 
64 
65 
66 
67 
68 
69 
70 

71 
72 



oooo: 



000024 
000026 
000027 
000030 
000031 
000032 
000033 
000034 
000036 



000042 
000043 
000044 
000046 
000050 



103004 



103004 



103756 
005767 

000024 

001004 



000010 
115 
131 
120 
122 
1 1 7 
107 
000040 
000000 



000040 000016 



002 

003 

046600 

070277 

016041 



FLG.JR = 10 

.F'SECT GUETST 
i EXECUTABLE SECTION 



(REQUEST AND JOB 
fREQUEST INDICATOR 



start: 



1*: 



.LOOKUP #AREA>*16f*LKUP (.LOOKUP QUEUE 



11$: 

2$: 



MERR! 



BCC 

.PR^NT 
.EXIT 
.URITW 

BCC 

.PRINT 
.EXIT 
.READU 



BCS 
TST 



BNE 

.PRINT 

.EXIT 



.PRINT 
.EXIT 



1« (ERROR? 

♦LUPERR (YESf print TEXT 

(AND QUIT 
*AREA>*16>»REQSTr*6 (SEND INITIAL 

(REQUEST TO QUEUE 
2» (ERROR? 

♦REQERR (YESf PRINT TEXT 

(AND QUIT 
*AREAr*16.*REPLY»*6 (UAIT FOR ACK FROM 

(QUEUE. WORD COUNT OF 

(ACK IN reply; f TEXT IN 

(REQST! . 
11$ (BRANCH ON ERROR 

REQST (ACK OK? (FIRST WORD OF 



MERR 
♦ACKMSG 



♦NAKMSG 



(ACK SHOULD BE 0) 
(BRANCH ON ERROR 
(PRINT TEXT 

(END OF LAB EXPERIMENT; 
(RAW DATA SENT TO 
(LINE P(?INTER. 
(PRINT ERROR TEXT 
(AND QUIT 



.psect ouedta 
( block for .lookup on queue 
lkup: 



.RAD50 
.A5CIZ 



/MQ/ 
/QUEUE/ 



051750 
121 
125 
105 
125 
105 
000 



area: .BLKU 5 
( ack from queue goes here 
000000 reply: .word o 
( flock for request 



reqst:: .word flg.jr 
.ascii /myprog/ 



.word jobblk 

.WORD 



( BLOCK FOR JOB 
JOBBLK: .WORD 
.BYTE 



(EMT AREA 



(WORD COUNT FROM .READU 



(INITIAL REQUEST 
(CALLING PROG NAME 



(ADDR OF JOB BLOCK 

(END OF INITIAL REQUEST 



::FLG. JR + FLG.HD + FLG.CP> (FLAGS FOR JOB » 

(BANNERS. AND COPIES 
?,3 (2 COPIESf 3 BANNERS 



■RAD50 /LP/ 

. RAD50 /RAWDTA/ 



(SEND TO PRINTER 
(LOGICAL JOB NAME FOR 
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Figure 3-23: QUEUE Example Program (Cont.) 

73 JFILE OF RAW HATA 

74 000052 000001 .WORD 1 ;ONE FILE FOLLOWS 
75 

76 ; BLOCK FOR FILE 

7 7 

78 000054 000000 FILFiLKI .WORD iNO FLAGS, USE DEFAULTS 

7? 0000;>6 000 .BYTE 0,0 fDEFAULT BANNERS, COPIES 

oooof;7 000 

30 000040 015270 .RAD50 /DK/ SFILESPEC OF FILE TO BE 

81 000062 100014 .RACiSO /TSTFIL/ JQUEUED. 

000064 023364 
(32 000066 014474 .RAClSO /BAT/ 

B3 

84 .NLIST BEX 

(35 
B6 ; MESSAGES 

8 7 

(3B 000070 115 LUPERR! .ASCIZ /hYPR06-F -QUEUE not running/ 

(39 000123 115 REQERR; .ASCIZ /MYPROG-F- I n i t i 3 1 reauest error/ 

90 000162 115 NAKhSG! .ASCIZ /MYPROG-W-OUEUE acknowledgment neSative/ 

91 000231 115 ACKMSG; .ASCIZ /MYPROG- I -QUEUE acknow 1 edsment OK/ 
92 

93 .EVEN 

94 .LIST BEX 

95 000000' .ENB START 

SYHBOL TABLE 

ACKMSG 000231R 003 FLG.JR= 000010 REPLY 000022R 003 

AREA OOOOIOR 003 JOBBLK 000040R 003 REQERR 000123R 003 

FILBLK 000054R 003 LKUP OOOOOOR 003 REQST 000024RG 003 

FLG.CP= 000002 LUPERR 000070R 003 START OOOOOOR 002 

FLG.tiE= 000001 HERR 000150R 002 ...yi = 000003 

FLG.Hri= 000004 NAKMSG 000162R 003 . . . V2 = 000027 

. ABS. 000000 000 

000000 001 

QUETST 000160 002 

QUEOTA 000272 003 

ERRORS detected: 

VIRTUAL MEMORY USED! 9216 WORDS ( 36 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 73 PAGES 
, MYPR06/L : TTM=MYPROG 



3.6 Data Structures 



The following sections describe some of the data structures in the Resident 
Monitor. 

3.6,1 Fixed Offsets 

Some words always have fixed positions relative to the start of the Resident 
Monitor. These words are called fixed offsets. In general, they contain 
either status words or pointers to other significant information. The fixed 
offset area in RMON is located at the start of the RTDATA p-sect. 

To access the fixed offsets from a running program, use the .GVAL pro- 
grammed request, as follows: 

.GVAL #area,#offse 
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Here, area represents a two-word argument block, and offse is a byte offset 
from Table 3-8. Your programs should never modify the contents of the 
fixed offsets. 

Table 3-8: Resident Monitor Fixed Offsets 



Offset 



Byte 
Length 
Symbol (Octal) 



Description 



$RMON 



4 


$CSW 


240 


244 


$SYSCH 


12 


246 




2 


250 




2 


252 


I.SERR/ 
I.SPLS 


2 


254 


I.SPLS 


2 


256 


BLKEY 


2 



260 



CHKEY 



262 


$DATE 


2 


264 


DFLG 


2 


266 


$USRLC 


2 



270 QCOMP 



Common interrupt entry point; contains the in- 
struction JMP $INTEN. The .INTEN macro 
uses it. 

Background job channel area (16 decimal chan- 
nels; each is five words long). 

Internal channel used for system functions; the 
Keyboard Monitor uses this channel. 

SJ only: Reserved. 

SJ only: Reserved. 

SJ only: An indicator for hard or soft errors. 

SJ only. 

Segment number of the directory now in 
memory. A value of implies that no directory 
is there. See Section 2.2.3.2 for a method of in- 
hibiting directory caching. 

Device index and unit number of the device 
whose directory is in memory. The low byte con- 
tains the device index into the monitor tables; 
the high byte is the unit number. 

Current date value. 

"Directory operation in progress" flag. This is 
non-zero to inhibit CTRL/C from aborting a job 
while a directory operation is in progress. 

Address of the normal USR area. This is where the 
USR resides when it is called into memory by the 
background job and location 46 is 0. In other words, 
the foreground job must provide space for the USR 
to swap. (Note: if the foreground job calls in the 
USR and location 46 is 0, the foreground job aborts.) 
See Chapter 2 for information on USR swapping. 

Address of the I/O exit routine for all devices. The 
exit routine is an internal queue management 
routine through which all device handlers exit once 
the I/O transfer is complete. Any new device 
handlers you add to RT-11 must also use this exit 
location; use the .DRFIN macro in your handler to 
generate the exit code automatically. 
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Table 3-8: Resident Monitor Fiixed Offsets (Cont.) 



Offset Symbol 



Byte 
Length 
(Octal) 



Description 



272 



274 



276 



277 



300 



SPUSR 



SYUNIT 



SYSVER 



SYSUPD 



CONFIG 



302 SCROLL 
304 TTKS 



306 


TTKB 


2 


310 


TTPS 


2 


312 


TTPB 


2 


314 


MAXBLK 


2 



316 E16LST 

320 CNTXT 

322 JOBNUM 



2 Special device error word. Non RT-11 file- 

structured devices, such as magtape, use this word 
to report errors to the monitor. 

2 The high byte contains the unit number of the 

system device. This is the unit number of the device 
from which the system was bootstrapped. 

1 Monitor version number. You can always access the 

version number in this fixed offset to determine if 
you are using the most recent version of the soft- 
ware. For RT-11 Version V04, this value is 4. 

1 Monitor release level. This number identifies the 
release level of the monitor version specified in byte 
276. For RT-11 Version V04.00, this value is 0. 

2 Configuration word. These 16 bits indicate informa- 
tion about either the hardware configuration of the 
system or a software condition. Another configura- 
tion word located at fixed offset 370 contains addi- 
tional data. See Section 3.6.1.1 for the meaning of 
each bit. 

2 Address of the VTll scroller. 

2 Address of the console keyboard status register. 

The default value is 177560. See Chapter 5 for 
details on changing the hardware console interface 
to another terminal. 

Address of the console keyboard buffer register. 
The default value is 177562. 

Address of the console printer status register. The 
default value is 177564. 

Address of the console printer buffer register. The 
default value is 177566. 

The maximum file size allowed in a length 
.ENTER programmed request. The default value is 
177777 octal blocks, allowing an essentially 
unlimited file size. You can change this value from 
within a running program (although this is not 
recommended), or by using SIPP to patch this 
location. 

2 Offset from the start of RMON to the dispatch table 

for EMTs 340 through 357. The BATCH processor 
uses this. 

2 FB and XM only: A pointer to the impure area for 

the current executing job. 

2 FB and XM only: The executing job's number. 
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Table 3-8: Resident Monitor Fixed Offsets (Cont.) 



Offset 



Byte 
Length 
Symbol (Octal) 



Description 



320 $TIME 
322 $TIME + 2 

324 SYNCH 



326 LOWMAP 



352 USRLOC 



362 



$MFPS 



372 SYSGEN 



374 USRARE 



376 ERRLEV 



24 



364 


GTVECT 


2 


366 


ERRCNT 


2 


360 


$MTPS 


2 



364 


SYINDX 


2 


366 


STATWD 


2 


370 


C0NFG2 


2 



SJ only: Two words of time of day. 



Address of monitor routine to handle .SYNCH re- 
quests. Your interrupt routines can issue the 
.SYNCH programmed request, which enters the 
monitor through this address to synchronize with 
the job they are servicing. 

Start of the low-memory protection map. This map 
protects vectors at locations through 476. See Sec- 
tion 3.6.1.2 for more information on the low-memory 
bitmap. 

A pointer to the current entry point of the USR. 
This may be 0, if the USR is not in memory; it may 
be the relocation code in USRBUF, if the USR was 
just brought into memory; it is the processing code, 
in all other cases. 

Address of VTll or VS60 display processor display 
stop interrupt vector (default is 320). 

Low byte is the error count byte for use by system 
utility programs. The high byte is reserved. 

Entry point of the move to PS routine. The .MTPS 
macro calls this routine to perform processor in- 
dependent moves to the Processor Status word. 

Entry point of the move from PS routine. The 
•MFPS macro calls this routine to do processor in- 
dependent moves from the Processor Status word. 

Index into the monitor device tables for the system 
device. See Section 3.6.5 for information on the 
device tables. 

Indirect file and monitor command state word. 

Extension configuration word. This is a string of 16 
bits indicating the presence of an additional set of 
hardware options on the system. See Section 3.6.1.3 
for the meaning of each bit. 

System generation features word. The bits in this 
word indicate the presence or absence of some 
system generation special features. See Section 
3.6.1.4 for the meaning of each bit. 

Size of the USR in bytes. Your program can use this 
information to dynamically determine the size of the 
region you need in order to swap the USR. (The USR 
is always resident in XM systems.) 

Error severity at which to abort indirect files. You 
can change this level with the SET ERROR com- 
mand. The default setting is ERROR. See Chapter 2 
for more information. 
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Table 3-8: Resident Monitor Fixed Offsets (Cont.) 



Offset Symbol 



Byte 

Length 
(Octal) 



Description 



377 



400 
402 



IFMXNS 



EMTRTN 
FORK 



404 


PNPTR 


2 


406 


MONAME 


4 


412 


SUFFIX 


2 



414 DECNET 



Depth of nesting of indirect files. The default 
nesting level is 3. You can change this value by us- 
ing SIPP to patch this location. Be sure to refer to 
offset 377 as a byte, not as a word. 

Internal offset for use by BATCH only. 

Offset to fork processor from the start of the Resi- 
dent Monitor. (Location 54 contains the starting ad- 
dress of RMON.) Use the .DREND macro in your 
device handler to automatically set up a pointer to 
the fork processor. 

Offset to the $PNAME table from the start of the 
Resident Monitor. 

Two words of Radix-50 containing the name of the 
current monitor file. 

One word of Radix-50 containing the suffix used by 
the current monitor to name device handlers. For S J 
and FB systems, this word is normally blank. For 
XM, it is normally X, right-justified. This word is 
set up by the bootstrap; you can modify it there (see 
the RT-11 Installation and System Generation 
Guide for details). 

Reserved. 



3.6.1.1 Configuration Word — The configuration word, CONFIG, indicates 
information about either the hardware configuration of the system or a soft- 
ware condition. Table 3-9 lists the bits and their meanings. Unused bits are 
reserved for future use by DICJITAL, 

Table 3-9: The Configuration Word, Offset 300 

Bit Meaning 

= SJ Monitor. 

1 = (If bit 12 = 0): FB Monitor. 
(If bit 12 = 1): XM Monitor. 

1 Reserved. 

2 1 = VTll or VS60 j^aphics display hardware 

exists. 

3 1 = BATCH is in control of the background. 

4 Reserved. 

5 = 60-cycle clock. 
1 = 50-cycle clock. 

The value of bit 5 is patchable to indicate 
the current line frequency. 
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Table 3-9: The Configuration Word, Offset 300 (Cont.) 

Bit Meaning 



6 1 = FPU floating-point liardware exists. 

7 = No foreground or system job is in memory. 
1 = A foreground or system job is in memory. 

8 1 = User is linked to the graphics scroller. 

9 1 = USR is permanently resident, via SET 

USR NOSWAP. (USR is always resident in 
XM and this bit is always set.) 

10 1 = The QUEUE program is running. 

11 1 = Processor is a PDP-11/03. The Processor 

Status word on this system cannot be ac- 
cessed by means of an address in the I/O 
page. 

12 1 = A mapped system is running under the XM 

monitor. 

13 1 = The system clock has a status register. 

14 1 = A KWll-P clock exists and programs can 

use it. 

15 1 = There is a system clock (L clock, P clock, or 

11/03-11/23 line-frequency clock). 



3.6.1.2 Low-Memoiy Protection Bitmap— RT-11 maintains a bitmap that 
reflects the protection status of low memory, locations through 477. This 
map is required in order to avoid conflicts in the use of the vectors. In FB 
and XM, the .PROTECT programmed request allows a program to gain ex- 
clusive control of a vector or a set of vectors. When a vector is protected, 
RMON updates the bitmap to indicate which words are protected. If a word 
in low memory is not protected, it is loaded from block of the executable 
file. If a word in low memory is protected, it is not loaded from block of the 
file. In addition, if the word is protected by a foreground job, it is not 
destroyed when you run a new background program. 

The bitmap is a 20-byte decimal table that starts 326 octal bytes from the 
beginning of the Resident Monitor. Table 3-10 hsts the offset from RMON 
and the corresponding locations represented by that byte. 

Each byte in the table reflects the status of eight words of memory. The 
first byte in the table controls locations through 17, the second byte con- 
trols locations 20 through 37, and so on. The bytes are read from left to 
right. Thus, if locations through 3 are protected, the first byte of the table 
contains 11000000. 

NOTE 

Only words are protected, not individual bytes. Thus, pro- 
tecting word means that bytes and 1 are both 
protected. 
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Table 3-10: Low-Memory Bitmap 

Locations 
Offset (Octal) 



326 


0-17 


327 


20-37 


330 


40-57 


331 


60-77 


332 


100-117 


333 


120-137 


334 


140-157 


335 


160-177 


336 


200-217 


337 


220-237 





Locations 


tffset 


(Octal) 


340 


240-257 


341 


260-277 


342 


300-317 


343 


320-337 


344 


340-357 


345 


360-377 


346 


400-417 


347 


420-437 


350 


440-457 


351 


460-477 



If locations 24 through 27 are protected, the second byte of the table con- 
tains 00110000. 

The leftmost bit of each byte represents lower memory locations; the 
rightmost bit represents higher memory locations. For example, to protect 
locations 300 through 307, the leftmost four bits of the byte at offset 342 
must be set to result in a value of 360 for that byte: 11110000. 

The SJ monitor does not support the .PROTECT programmed request. If 
you need to protect vectors in S3, either use SIPP to manually modify the 
bitmap or dynamically modify the bitmap from within a running program. 

For example, the following instructions protect locations 300 through 306 
dynamically: 

MOV @#54,R0 

BISB rB11110000,342(R0) 

Protecting locations with SIPF* means that the vector is permanently pro- 
tected, even if you rebootstrap the system. The dynamic method provides a 
temporary measure and does not remain effective across bootstraps. Be 
aware that the dynamic method involves storing data directly into the 
monitor. For this reason, DIGITAL recommends that you use SIPP to pro- 
tect vectors in SJ. 

The RT-11 monitor uses the low-memory bitmap to automatically protect 
some locations in low memory. The locations it protects are as follows: 

0-16 

24-32 

50-66 

100-102 (line-frequency clock) 

104-106 (if KWll-P selected as system clock) 

114-116 

244-246 

250-252 (for XM systems only) 

System device handler interrupt vector 

Interrupt vectors for loaded dtsvice handlers 

Vectors for all interfaces supported in a multi-terminal system 
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NOTE 

Vectors of device handlers that you load with the LOAD 
command are protected; vectors of device handlers that 
you bring into memory with the .FETCH programmed re- 
quest are not protected. 

3.6.1.3 Extension Configuration Word — The extension configuration word, 
CONFG2, indicates the presence of an additional set of hardware options on 
the system. Table 3-11 lists the bits and their meanings. Unused bits are 
reserved for future use by DIGITAL. 

Table 3-11: Extension Configuration Word, Offset 370 
Bit Meaning 

1 = Caclie memory is present. 

1 1 = Parity memory is present. 

2 1 = A readable switch register is present. 

3 1 = A writeable console display register is 

present. 

4-7 Reserved. 

8 1 = The Extended Instruction Set (E IS) option 

is present. 

9 = VTll display hardware exists if bit 2 at off- 

set 300 is set. 
1 = VS60 display hardware exists if bit 2 at off- 
set 300 is set. 

10-13 Reserved. 

14 1= The processor is a PDF- 11/70. 

15 1= The processor is a PDP-11/60. 

3.6.1.4 System Generation Features Word — The system generation features 
word, SYSGEN, indicates which major system generation features are pre- 
sent. Table 3-12 lists the meaning of each bit. Unused bits are reserved for 
future use by DIGITAL. In addition, do not set or clear any bits in this 
word yourself. 

Note that the values of the first three bits must correspond to the condi- 
tional variables you use when you assemble your device handler files. At- 
tempts to use handlers that are not compatible with the monitor cause the 
?KMON-F-Conflicting SYSGEN options error message to appear. 

3.6.2 Impure Area 

The impure area is an area of memory where the monitor stores all job- 
dependent data. For each job, the impure area contains job-specific informa- 
tion, such as terminal ring buffers and I/O channels. The monitor sets up 
the impure area and maintains its contents. 
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Table 3-12: System Generation Features Word, Offset 372 

Bit Meaning 



3-8 Reserved 



9 
10 



11-12 Reserved 



13 
14 



= The error logginig feature is present. 

= The memory management feature is 
present. 

= The device I/O time-out feature is present. 



= The memory parity feature is present. 
= The SJ mark time feature is present. 



= The multi-terminal feature is present. 
= The system job feature is present. 



15 Reserved. 



3.6.2.1 Single-Job Monitor Impure Area — In the SJ system, there is no 
distinct impure area for the single job. Instead, information relating to the 
job is stored in various places throughout the Resident Monitor. 

3.6.2.2 Foreground/Background Monitor Impure Area — In an FB system, the 
impure areas contain all the information the monitor requires to run two or 
more independent jobs. The information stored in the impure area is job- 
specific. The impure area for the background job is located at the start of 
the p-sect RMON in the Resident Monitor and it is permanently resident. 
The impure area for a foreground or system job is located in memory below 
the start of the job itself. The size of the impure area is the value of the 
global symbol in FMPUR, whic;h you can find by looking at your monitor's 
Unk map. 

The monitor maintains a table of one- word pointers to the impure areas of 
all jobs in the system. This table is located at $IMPUR, and is either eight 
or two words long, depending on whether the system job feature is present 
or not. 

In RT-11, a background job is always present. It is the Keyboard Monitor 
if no other background job exists. The foreground or system job impure 
area pointer may be if no such job is in memory. When you issue an FRUN 
command, the monitor creates an impure area for the foreground job. 
Similarly, the SRUN command creates an impure area for a system job. In 
both cases, the monitor also updates the job's $IMPUR entry to point to 
the impure area. 

Table 3-13 shows the contents of the impure area, which are the same for 
both the background and the foreground jobs. The offset in the table is the 
offset from the start of the impure area itself. In some cases, the contents of 
the impure area depend on which system generation features you select. 
These cases are indicated by a "Feature only:" phrase in the "Description" 
column. 
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Table 3-13: Impure Area 



ffset 


Symbol 


Byte 
Length 
(Octal) 





I.STATE 


2 


2 


I.QHDR 


2 


4 


I.CMPE 


2 


6 


I.CMPL 


2 


10 


I.CHWT 


2 



Description 



12 



14 



16 



20 



16 



36 



I.PCHW 



I.PERR 



I.TTLC 



LPTTI 



I.CNSL 



20 


unused 


2 


22 


I.TID 


2 


24 


I.JNUM 


2 


26 


LCNUM 


2 


30 


LCSW 


2 


32 


LIOCT 


2 


34 


LSCTR 


2 



I.BLOK 



Job state word bits. See Table 3-14 for the mean- 
ing of each bit. 

Head of available queue element linked list. 

Last entry in the completion queue. 

Head of the completion queue. 

Pointer to channel during I/O wait. When a job is 
waiting for I/O on a channel to complete, the ad- 
dress of that channel area is stored here. 

Saved I.CHWT during execution of a completion 
routine. 

Error bytes 52 and 53 saved during completion 
routines. 

Terminal input ring buffer Une count (for non- 
multi-terminal systems). 

Previous terminal input character (for non-multi- 
terminal systems). 

Multi-terminals only: Pointer to terminal control 
block (TCB) for this job's console terminal. 

Multi-terminals only: Unused. 

Pointer to job ID area, later in impure area. 

Job number of the job that owns this impure 
area. 

Number of I/O channels defined. The default is 
16 decimal; you can use .CDFN to define more. 

Pointer to the job's channel firea. 

Total number of I/O operations outstanding. 

Suspension counter. A value less than means 
the job is suspended. 

Job blocking bits. See Table 3-15 for the mean- 
ing of each bit. 



The following offsets are not guaranteed to remain constant from release to release. In fact, 
since the pointers and status words can vary depending on the special features you select 
through system generation, you should consult the link map from the monitor assembly to 
find the correct offsets for your system. Note that some items, such as the input and output 
ring buffers, have a variable length. 

— I. J ID 10 Job's terminal prompt string. If the system job 

feature is present, the length of I.JID is 14 octal. 

— I.LNAM 6 System jobs only: Logical job name in ASCII. 

— I.NAME 10 File name and file type, in Radix-50, of the runn- 

ing job. 
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Table 3-13: Impure Area (Conlt.) 



Offset Symbol 



Byte 
Length 
(Octal) 



Description 



I.SPLS 
I.TRAP 

I.FPP 



I.SPSV 


2 


I.SWAP 


4 


I.SP 


2 


I.BITM 


24 


I.CLUN 


2 


I.TTLC 


2 


I.IRNG 


2 


I.IPUT 


2 


I.ICTR 


2 


I.IGET 


2 


I.ITOP 


2 





TTYIN 


I.OPUT 


2 


I.OCTR 


2 


I.OGET 


2 


I.OTOP 


2 





TTYOUT 


I.QUE 


QWDSIZ 


I.MSG 


4 


I.SERR 


6 


I.'l'ERM 


2 


I.TRM2 


2 


I.SCCA 


2 


I.SCCI 


2 


I.DEVL 


2 


I.FPSA 


2 



Pointer to nonlinked .DEVICE list. 

Address of trap to 4 and 10 routine defined via 
.TRPSET. 

FPU only: Address of FPP exception routine 
defined via .SFPA. 

XM only: Bottom of saved SP data. 

Pointer to extra swap information specified in 
the .CNTXSW programmed request. 

Saved stack pointer. 

Bitmap for protection. 

Multi- terminals only: LUN of job's console. 

Multi-terminals only: Terminal input ring buffer 
line count. 

Input ring buffer low limit. 

Input PUT pointer for interrupts. 

Input character count. 

Input GET pointer for .TTYIN. 

Input ring buffer high limit. 

Input ring buffer. 

Output PUT pointer for .TTYOUT. 

Output character count. 

Output GET pointer for interrupts. 

Output ring buffer high limit. 

Output ring buffer. 

The initial queue element; 16 octal bytes (24 
bytes if XM). 

The'internal message channel. 

The third word of the message channel is used as 
the hard/soft error flag. 

Terminal status word. 

Terminal status word 2. 

CTRL/C terminal status word set via .SCCA. 

XM only: PARI value of I.SCCA for XM. 

Pointer to linked .DEVICE Ust. 

XM and FPU only: Pointer to FPU save area, 
later in impure area. 



Resident Monitor 3-57 



Table 3-13: Impure Area (Cont.) 



Offset 



Symbol 


Length 
(Octal) 


I.SCOM 


36 


I.SCOM 


40 


I.RSAV 


20 


I.WPTR 


2 


I.RGN 


RGWDSZ 


I.WNUM 


2 





WNWDSZ 


I.FSAV 


62 


I.VHI 


2 



Description 



LSCHP 



I.SYCH 



14 



XM only: system communication save area (for 
non-multi-terminal systems). 

XM and multiTterminals only: System com- 
munication save area. 

XM only: Register save area. 

XM only: Pointer to window control blocks, at 
LWNUM later in impure area. 

XM only: Region control blocks. 

XM only: Number of window blocks. 

XM only: Window control blocks. 

XM and FPU only: FPU save area. 

XM only: Virtual high limit of job; nonzero if 
linker A^ option used. 

Pointer to the job's system channel. The monitor 
uses this channel for its own calls, such as 
.DSTATUS. 

The job's system channel, for all foreground and 
system jobs. The background job's channel is in 
the fixed offset area of the Resident Monitor. 



Job State Word Bits 

The job state word, I, STATE, indicates status information about a job. 
Table 3-14 shows the meaning of each bit. Unused bits are reserved for 
future use by DIGITAL. 

Table 3-14: Job State Word Bits, Offset 
Mnemonic Bit Meaning When Set 



ABPND$ 





An abort has been requested for this job. 


BATRN$ 


1 


BATCH is running for this job. 


CSIRNS 


2 


The CSI is running for this job. 


USRRNS 


3 


The USR is running for this job. 




4 


Reserved. 


ABORTS 


5 


The job is being aborted. 




6 


Reserved. 


CPENDS 


7 


This job has a completion routine pending. 




8-11 


Reserved. 
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Table 3-14: Job State Word Bits, Offset (Cont.) 
Mnemonic Bit Meaning When Set 



WINDW$ 


12 


This is a virtual job. 




13-14 


Reservecl. 


CM]PLT$ 


15 


A compl(3tion routine is running for this job. 



Job Blocking Bits 

The job blocking word, I.BLOK, indicates which condition is blocking a job. 
Unused bits are reserved for future use by DIGITAL. Table 3-15 shows the 
meaning of each bit. 

Table 3-15: Job Blocking Bits, Offset 36 

Mnemonic Bit Meaning When Set 

0-3 Reserved. 

USRWT$ 4 The job is waiting for the USR. 

5 Reserved. 

KSPNDS 6 The job is suspended as a result of the monitor 

SUSPEND command. 

7 Reserved. 

EXITS 8 The job is waiting for all I/O to complete. 

N0IIUN$ 9 The job is not running (that is, it is a foreground or 

system job that has completed). 

SPND$ 10 The job is suspended. 

CHNWT$ 11 The job is waiting for I/O on a channel to complete. 

TTOEM$ 12 The job is waiting for the output ring buffer to be 

empty. 

TTO WT$ 13 The j ob is waiting for room in the output ring buffer. 

TTIWT$ 14 The job is waiting for terminal input. 

15 Reserved. 



3.6.3 Queue Element Format Summary 

This section summarizes the formats of the various types of queue 
elements. For detailed information on clock support and timer service, see 
Section 3.2, which also describes the timer queue element. Section 3.3 con- 
tains more information on the queued I/O system and includes descriptions 
of the I/O queue element, the completion queue element, and the synch 
queue element. 
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3.6.3.1 I/O Queue Element — Figure 3-24 shows the format of an I/O queue 
element. 



Figure 3-24: I O Queue Element Format 



NAME 


OFFSET 


CONTENTS 


Q.LINK 





LINKTO NEXT QUEUE ELEMENT;0 IF NONE 


Q.CSW 


2 


POINTER TO CHANNEL STATUS WORD IN I/O 
CHANNEL (SEE FIGURE 3-29) 


Q.BLKN 


4 


PHYSICAL BLOCK NUMBER 


Q.FUNC 

Q.UNIT 

ajNUM 


6 

7 
7 


RESERVED 
(1 BIT) 


JOB 

NUMBER 
(4 BITS) 
0= BG 


DEVICE 

UNIT 

OBITS) 


SPECIAL 
FUNCTION 
CODE 
(8 BITS) 


Q.BUFF 


10 


USER BUFFER ADDRESS (MAPPED THROUGH PARI 
WITH Q.PAR VALUE, IF XM) 


Q.WCNT 


12 


(if <0, OPERATION IS WRITE 
WORD COUNT <IF=0, OPERATION IS SEEK 

(if >0, OPERATION IS READ 
THE TRUE WORD COUNT IS THE ABSOLUTE 
VALUE OF THIS WORD. 


Q.COMP 


14 


COMPLETION (\P 0, THIS IS WAIT-MODE I/O 
ROUTINE lIF 1, JUST QUEUE THE REQUEST * 
CODE < AND RETURN 

ilF EVEN, COMPLETION ROUTINE 

(^ADDRESS 


Q.PAR 


16 


PARI VALUE (XMONLY) 






RESERVED (XMONLY) 






RESERVED (XMONLY) 



Figure 3-25: Completion Queue Element Format 



NAME 


OFFSET 


CONTENTS 


Q.LINK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 




2 


RESERVED 




4 


RESERVED 




6 


RESERVED 


Q.BUFF 


10 


CHANNEL STATUS WORD 


Q.WCNT 


12 


OFFSET FROM START OF CHANNEL AREA TO THIS CHANNEL 


Q.COMP 


14 


COMPLETION ROUTINE ADDRESS 






THREE ADDITIONAL WORDS ARE PRESENT IN XM SYSTEMS. THEY 
ARE UNUSED, AND ARE RESERVED FOR FUTURE USE BY DIGITAL. 
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3.6.3.2 Completion Queue Element — Figure 3-25 shows the format of a com- 
pletion queue element. 

3.6.3.3 Synch Queue Element — Figure 3-26 shows the format of a synch 
queu(} element. 

Figure 3-26: Synch Queue Element Format 



NAME ' 


OFFSET 


CONTENTS 


Q.LINK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 


Q.CSW 


2 


JOB NUMBER 


Q.BLKN 


4 


RESERVED 


0:.FUNC 


6 


RESERVED 


Q.BUFF 


10 


SYNCH ID 


Q.WCNT 


12 


-1 (CUE THAT THIS IS A SYNCH ELEMENT) 


Q.COMP 


14 


SYNCH ROUTINE ADDRESS 






THREE ADDITIONAL WORDS ARE PRESENT IN XM SYSTEMS. THEY 
ARE UNUSED, AND ARE RESERVED FOR FUTURE USE BY DIGITAL. 



3.6.3.4 Fork Queue Element — Figure 3-27 shows the format of a fork queue 
element. 



Figure 3-27: Fork Queue Element Format 



NAME 


OFFSET 


CONTENTS 


F.BLNK 





LINK TO NEXT QUEUE ELEMENT; IF NONE 


F.BADR 


2 


FORK ROUTINE ADDRESS 


F.BR5 


4 


re; SAVE AREA 


F.BR4 


6 


R4 SAVE AREA 



3.6.3.15 Timer Queue Element — Figure 3-28 shows the format of a timer 
queue element. 

3.6.4 I/O Channel Format 

Figure 3-29 shows the format of an I/O channel. Since each channel uses 
five v/ords, the size of the monitor's channel area is five times the number of 
channels. RT-11 allocates 16 channels for each job. The channel area is 80 
decimal words long. For SJ, a single channel area is located in RMON. For 
FB and XM, one channel area for each job is located in the job's impure 
area. The .CDFN programmed request can provide more channels. Table 
3-16 shows the significant bitsi in the Channel Status Word. 
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Figure 3-28: Timer Queue Element Format 



NAME 


OFFSET 


CONTENTS 


C.HOT 





HIGH-ORDER TIME 


CLOT 


2 


LOW-ORDER TIME 


CLINK 


4 


LINK TO NEXT QUEUE ELEMENT; IF NONE 


CJNUM 


6 


OWNER'S JOB NUMBER 


CSEQ 


10 


OWNER'S SEQUENCE NUMBER ID 


CSYS 


12 


-1 IF SYSTEM TIMER ELEMENT; 
-3 IF .TWAIT ELEMENT IN XM 


CCOMP 


14 


ADDRESS OF COMPLETION ROUTINE 






THREE ADDITIONAL WORDS ARE PRESENT IN 
XM SYSTEMS. THEY ARE UNUSED, AND ARE 
RESERVED FOR FUTURE USE BY DIGITAL. 



Figure 3-29: I/O Channel Description 



NAME 


OFFSET 


CONTENTS 







CHANNEL STATUS WORD 


C.SBLK 


2 


STARTING BLOCK NUMBER OF THIS FILE 
(0 IF NON-FILE-STRUCTURED) 


CLENG 


4 


LENGTH OF FILE (IF OPENED BY .LOOKUP) 
SIZE OF EMPTY AREA (IF OPENED BY .ENTER) 


C.USED 


6 


HIGHEST BLOCK WRITTEN 


C.DEVQ 


10 


DEVICE 
UNIT NUMBER 


NUMBER OF REQUESTS 
PENDING ON THIS CHANNEL 



3.6.5 Device Tables 

Tables in the Resident Monitor keep track of the devices on the RT-11 
system. These tables are contained in the module SYSTBL.MAC, which is 
created by system generation and assembled separately from the module 
RMON. SYSTBL is Unked with RMON and other modules to form the Resi- 
dent Monitor. The symbol $SLOT in SYSTBL, which is defined at system 
generation time, defines the maximum number of devices the system can 
have. The value of $SLOT is greater than or equal to 3, and less than or 
equal to 31 decimal. 

3,6.5,1 $PNAME Table — The permanent name table is called $PNAME. It 
is the central table around which all the others are constructed. The total 
number of entries is fixed at assembly time; you can allocate extra slots 
then. Entries are made in $PNAME at monitor assembly time for each 
device that is built into the system. 
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Table 3-16: Channel Status Word (CSW) 
E(it Me'aning 

Hard error bit. 

= No error. 

1 = Hard error. 

1-5 Index into the SPNAME table and other device tables. 

6 RENAME flag. 

= No RENAME is in progress. 

1 = A RENAME operation is in progress. 

7 = The file was opened with a .LOOKUP. The monitor does 

not modify the directory when the file is closed. 
1 = The file was opened with an .ENTER. The monitor 
modifies the directory when the file is closed. 

8-12 The number of the directory segment containing this 

entry. 

13 End-of-file (EOF) bit. 

= No end-of-file. 

1 = End-of-file was found on this channel. 

14 Reserved. 

15 = The channel is free. 

1 = The channel is active. 



Each table entry consists of a single word that contains the Radix-50 code 
for the two-character physical device name. (For example, the entry for 
DECtape is .RAD50 /DT/.) Th(5 TT device must be first in the table; the 
system device is always second. After that, the position of a device in this 
table is not critical. Once the entries are made into this table, their relative 
position (that is, their order in the table) determines the general device in- 
dex used in various places in the monitor. Thus, the other tables are 
organized in the same order as $PNAME. The offset of a device name entry 
in $PNAME serves as the index into the other tables for a given device. 

The bootstrap checks the system generation parameters of a handler with 
those of the current monitor (by inspecting the low three bits of SYSGEN 
at RMON fixed offset 372), and zeroes the $PNAME entry for that device if 
the parameters do not match. The INSTALL monitor command cannot in- 
stall a handler whose conditional parameters do not match those of the 
monitor. 

3.6.5.2 $STAT Table — The device status table is called $STAT. Entries to 
this table are made at assembly time for those devices that are permanently 
resident in the RT-11 system, such as TT and MQ in FB and XM systems. 
When the system is bootstrapped, the entries for all other devices are filled 
in when the handler is installed by the bootstrap or the INSTALL monitor 
command. Each device in the system has a status entry in its correspon- 
ding slot in $STAT. The device status word identifies each physical device 
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and provides information about it, such as whether it is random or sequen- 
tial access. The device status word is part of the information returned to a 
running program by the .DSTATUS programmed request. See Chapter 7 
for details on the status word. 

3.6.5.3 $DVREC Table — The device handler block number table is called 
$DVREC. Entries to this table are made at bootstrap time for devices that 
are built into the system, and at INSTALL time for additional devices. The 
entries are the absolute block numbers where each of the device handlers 
resides on the system device. Since handlers are treated as files, their posi- 
tions on the system device are not necessarily fixed. Thus, each time the 
system is bootstrapped, the handlers are located and $DVREC is updated 
with their locations on the system device. The pointer in $DVREC points to 
block 1 of the file. (Because handlers are linked at 1000, the actual handler 
code starts in the second block of the file.) A zero entry in the $DVREC 
table indicates that no handler for the device in that slot was necessary 
(such as TT or MQ in FB and XM systems). (Note that if block of the 
handler file resides on a bad block on the system device, RT-11 cannot in- 
stall or fetch the handler.) Note also that is a valid $DVREC entry for per- 
manently resident devices. 

3.6.5.4 SENTRY Table — The handler entry point table is called $ENTRY. 
Entries in this table are made whenever a handler is loaded into memory by 
either the .FETCH programmed request or by the LOAD keyboard monitor 
command. The entry for each device is a pointer to the fourth word of the 
device handler in memory. The entry is zeroed when the handler is removed 
by the .RELEASE programmed request or by the UNLOAD keyboard 
monitor command. 

Some device handlers are permanently resident. These include the system 
device handler and, for FB and XM systems, the TT handler. The SENTRY 
values for such devices are fixed at boot time. 

3.6.5.5 $HSIZE Table — Each entry in the $HSIZE table contains the size of 
a device, in blocks. The value is for a non-file-structured device. For 
devices that accept multi-size volumes, the entry contains the size of the 
smallest possible volume. 

3.6.5.6 SDVSIZ Table — Each entry in the $DVSIZ table contains the size of 
a device handler, in bytes. This value indicates the amount of memory need- 
ed to load each handler. 

3.6.5.7 $UNAM1 and $UNAM2 Tables — The tables that keep track of logical 
device names and the physical names that are assigned to them are called 
$UNAM1 and $UNAM2. Entries are made in these tables when the 
ASSIGN monitor command is issued. The physical device name is stored in 
$UNAM1 and the logical name associated with it is stored in the correspon- 
ding slot in $UNAM2. When the system is first bootstrapped, there are 
two assignments already in effect that associate the logical names DK and 
SY with the device from which the system was booted. The value of $SLOT, 
which is determined at system generation time, Umits the total number of 
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logical name assignments. Thus, you can issue one ASSIGN command for 
each device in your system, (The initial SY and DK assignments at 
bootstrap time do not come out of your total.) 

The $UNAM1 and $UNAM2 tables are not indexed by the $PNAME table 
offset. The fact that the tables are the same size is interesting, but not 
significant. 

3.6.5.8 $OWNER Table — The device ownership table is called $OWNER 
and it is used in the FB and XM environments to arbitrate device owner- 
ship. The table is ($SL0T*2) words in length and is divided into two-word 
entries for each device. Entries are made into this table when the LOAD 
keyboard monitor command is issued. Each two- word entry is in turn divid- 
ed into eight four-bit fields capable of holding a job number. The low four 
bits of the first byte correspond to unit 0, and the high four bits correspond 
to unit 1. The low four bits of the next byte correspond to unit 2, and so on 
(see Figure 3-30). Thus, each device is presumed to have up to eight units, 
each assigned independently of the others. However, if the device is non- 
file-structured, units are not assigned independently: the monitor ASSIGN 
code ensures that ownership of all units is assigned to one job. 



Figure 3-30: $OWNER Entry 

DEVICE UNIT# 



3 


2 


1 





OWNER # 


OWNER # 


OWNER # 


OWNER # 


OWNER # 


OWNER # 


OWNER # 


OWNER # 



DEVICE UNIT# 7 6 5 4 

When a background job, a foreground job, or a system job attempts to ac- 
cess a particular unit of a devic;e, the monitor checks to be sure the unit be- 
ing accessed is either pubUc or belongs to the requesting job. If another job 
owns the unit, a fatal error is generated. 

The device is pubUc if the four bit field is 0. If the device is not public, the 
field contains a code equal to tlie job number plus 1. Since job numbers are 
always even, the ownership code is odd. For example, in a distributed 
foreg^round/background system, the owner field value for the background 
job is 1; for the foreground job it is 3. In a foreground/background system 
with the system job feature th(} owner field value for the background job. is 
still 1; for the foreground job it is 17. The owner field value for a system job 
is 1 jjlus the job number. 

3.6.5.9 Adding a Device to the Tables — You can create free slots in the tables 
by deleting or renaming one or more of the device handler files from the 
system device and rebooting the system, or by issuing the REMOVE 
monitor command. The INSTALL monitor command can install a different 
device handler into the table after the system has been booted. However, 
INSTALL does not make a device entry permanent. For more information 
on installation, the DEV macro, and the bootstrap, see Chapter 7. 
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Chapter 4 

Extended Memory Feature 



Aftor introducing RT-ll's extended memory feature, this chapter provides 
an overview of the hardware components that are the basis of the extended 
memory system. (The term extended memory refers to physical memory 
above the 28K word boundarj;^ that can be accessed only by using special 
hardware. Low memory is the physical memory between and 28K words. 
In some systems with an additional 2K words of low memory, low memory 
extends to 30K words and there is no extended memory.) It then shows how 
RT-11 implements support for extended memory, and explains how to 
design, code, and execute a program in an extended memory environment. 
Following these demonstrations is a discussion of the implications of ex- 
tended memory support for other system software components and a 
description of all the restrictions you must observe when working with ex- 
tended memory. Lastly, this chapter describes how to debug an extended 
memory application program and provides a sample program that uses 
double buffering in extended itnemory. 



4.1 Introduction 



The following sections present a brief overview of the circumstances that 
led to the RT-11 extended memory implementation. Read it to gain an 
understanding of the limitations of 28K-word systems and the means by 
which RT-11 circumvents these limitations. 



4.1.1 16-Bit Addressing 

Each computer in the PDP-11 family can directly address 32K words. A 
PDP-11 computer can never address more than this amount of memory 
directly because its architecture provides only 16-bit addresses. Figure 4-1 
illustrates this addressing limitation. Since the PDP-11 computer can ad- 
dress bytes individually, you can see from the illustration why its address 
space is limited to 32K words,, 

Remember that one K equals 1024 decimal, or 2 raised to the 10th power. 
The RT-11 Pocket Guide provides a convenient reference chart of K-words 
and their equivalent octal numbers. 

In unmapped PDP-11 systems (those not using extended memory), the 
highest 4K words of address space, called the I/O page, are reserved for 
device registers, general registers, and so on. Thus, only 28K words of ad- 
dress space are left for use by t;he operating system software and programs. 
On a system with 28 K words of memory, all 28K words are available. 
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Figure 4-1: 16-Bit Word Addressing Space Limitation 
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THE SAME VALUE EXPRESSED IN OCTAL IS 177777. 

THE SAME VALUE EXPRESSED IN DECIMAL IS 65535. 

SINCE IS A VALID LOCATION, THE PDP-1 1 CAN ADDRESS 65536 UNIQUE BYTE LOCATIONS. 
THUS, THE PDP-1 1 (WHICH IS A BYTE-ADDRESSABLE COMPUTER) ADDRESSES 64K BYTES OF 
MEMORY, OR 32K WORDS OF MEMORY. 



4.1.2 Virtual and Physical Addresses In a 28K-Word System 

A virtual address is a value in the range through 177777. It is a 16-bit ad- 
dress within a program's 32K-word address space. 

A physical address is the actual hardware address of a specific memory 
location. Physical addresses are not limited to 16 bits. 

Figure 4-2 shows the relationship between virtual address space and 
physical address space in an RT-11 system with 28K words of memory. 
Note that in this system, which could be running either the SJ or FB 
monitor, there is a one-to-one correspondence between virtual and physical 
addresses. For example, virtual address 20000 corresponds directly to 
physical address 020000. 



4.1.3 Circumventing the 28K-Word Memory Limitation 

Before RT-11 provided support for extended memory, systems were 
limited to using 28K words of memory. Programmers have traditionally 
used two mechanisms to circumvent the 28K-word available memory hmita- 
tion. One of the mechanisms is called chaining: one program calls a second 
program at exit time; the second program provides additional processing 
for the data the original program passes to it. The MACRO- 11 assembler, 
for example, assembles a MACRO-11 source file and chains to CREF, 
which produces the cross-reference Usting. One way, then, to run a program 
that is larger than the amount of memory available is to divide the program 
into two or more functionally distinct parts. Then, when the first program 
finishes, it can start up the second program by chaining to it. 

Another way to run a program that is larger than the amount of memory 
available is to divide the program into overlay segments. Separate 
segments can then take turns residing in the same place in physical 
memory. By using overlays you can run a very large program in a much 
smaller amount of physical memory. 
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Figure 4-2: Virtual and Physiical Addresses in a 28K-Word System 
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In both chaining and overlaying, instructions and data in the separate pro- 
grams or segments use both the same virtual addresses and the same loca- 
tions in physical memory. Projjrams or segments not currently in memory 
reside on an auxiliary storage volume. Figure 4-3 illustrates chaining; 
Figure 4-4 shows overlaying. 



4.1.4 18-Bit Addressing 

Although PDP-11 software usies 16-bit words, it is possible to access more 
than 32K words of memory through a design that edlows the UNIBUS or 
QBUS and the CPU to use 18-bit words. This means that the bus and CPU 
can address up to 124K words of physical memory, plus a 4K-word I/O 
page, Figure 4-5 shows the addressing range for an 18-bit word. 
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Figure 4-3: Chaining 
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4.1.5 Virtual and Physical Addresses with Extended Memory 
Hardware 

The virtual addresses your program uses are always limited to 16 bits so 
that your program's virtual address space is always limited to 32K words. 

However, an 18-bit address can reference any location between and 128K 
words and in RT-11 systems with more than 28K words of memory, 
physical locations are referenced by the hardware as 18-bit addresses. 

As Figure 4-6 shows, there can no longer be a direct one-to-one cor- 
respondence between virtual and physical addresses. 



4.1.6 Circumventing the 32K-Word Address Limitation 

As the price of memory continues to drop, it becomes more and more feasi- 
ble to provide PDP-11 systems with more than 28K words of memory. 
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Figure 4-4: Overlaying 
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Figure 4-5: 18-Bit Word Addressing Range 
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THE SAME VALUE EXPRESSED IN OCTAL IS 777777. 

THE SAME VALUE EXPRESSED IN DECIMAL IS 262143. 

SINCE IS A VALID LOCATION, THE UNIBUS AND CPU CAN ADDRESS 262144 
UNIQUE BYTE LOCATIONS. THUS, THE UNIBUS AND CPU HAVE 256K BYTES 
OR 128K WORDS OF PHYSICAL ADDRESS SPACE. 
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Figure 4-6: Virtual and Physical Addresses with Extended Memory 
Hardware 



PHYSICAL ADDRESS 
SPACE 



128K 



UP TO 124K 



VIRTUAL 
ADDRESS SPACE 






32K 



32K 



I/O PAGE 






MEMORY 



16-BIT ADDRESSES 



18-BIT ADDRESSES 



Since the UNIBUS already has the ability to address up to 128K words, it 
remains the task of the hardware — the Memory Management Unit — and 
the operating system software to set up a correspondence between a pro- 
gram's virtual addresses and physical memory locations so that programs 
can access all of memory. 

If you select extended memory as a special feature at system generation 
time, you can take advantage of the 18-bit addresses. The extended 
memory feature permits programs, which are still restricted to using 16-bit 
words, to access 124K words of physical memory. RT-11 implements sup- 
port for extended memory through a combination of hardware and software 
components. 
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Through its extended memory (XM) monitor, RT-11 provides a mechanism 
to associate a virtual address with a physical address. This process is called 
mapping. RT-1 1 permits programs to access extended memory by mapping 
their virtual addresses to physical locations in memory. In summary: 

• Every location in memory has an 18-bit physical address; there are 
more physical addresses than virtual addresses. 

• A program cannot access specific physical addresses unless its virtual 
addresses are mapped to those physical locations. 

• Programs can access all the available physical memory by using their 
virtual addresses over and over again, but with different mapping each 
time. 

Section 4.3 presents more material on mapping. Be sure you understand the 
hardware concepts discussed in the next section before you proceed to 4.3. 

In an extended memory system, programs are no longer limited to using 
28K words of memory. Howeveir, they must still deal with the 32K-word ad- 
dressing limitation. Typically, large programs are still divided into smaller 
segments, as in the 28K-word systems. While the instructions and data in 
separate segments of a program share the same virtual addresses, they can 
have unique physical addresses. Figure 4-7 shows a program that is di- 
vided into three overlay segments. The three segments are resident 
simultaneously in extended memory, but they share the virtual addresses 
in overlay region 1. 



4.2 Hardware Concepts 



There are three hardware requirements for an RT-11 extended memory 

system: 

• At least 32K words of memory 

• The Extended Instruction Set (EIS) option 

• A Memory Management LFnit 

This manual provides an overview of the memory management hardware 
and its functions. The best sources of detailed information on the memory 
management hardware are the liardware manuals for the KTll-C, -CD, and 
-D Memory Management Unitsi. Their full titles and order numbers are as 
follows: 

KTll-C, CD Memory Management Unit User's Manual: EK-KTllC-OP-001 

KTll-D Memory Management Option Manual EK-KTllD-TM-002 

KTll-D Memory Management Option User's Manual: EK-KTllD-OP-001 

Another source of information (m the memory management hardware is the 
PDP-11 Processor Handbook. 
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Figure 4-7: Program Segments Sharing Virtual Address Space 
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SEGMENTS 1, 2, AND 3 HAVE UNIQUE PHYSICAL ADDRESSES, BUT 
THEY TAKE TURNS USING THE SAME SET OF VIRTUAL ADDRESSES. 



Note that it is not necessary to learn the details of how the Memory 
Management Units function in order to understand and use the RT-11 ex- 
tended memory system. These manual references are provided for your con- 
venience should you choose to do some further background reading. 



4.2.1 Memory Management Unit 

The central component of an XM system is a hardware option referred to 
generally as the Memory Management Unit, or MMU. DIGITAL manufac- 
tures several types of Memory Management Units, including the KTll-C, 
the KTll-D, and the KTll-CD. RT-11 supports the minimal set of func- 
tions common to all the memory management units. 
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The function of the Memory Management Unit is to intercept a 16-bit vir- 
tual address generated by the processor and convert it to an 18-bit physical 
address. Figure 4-8 illustrates this process. 

Figure 4-8: MMU Address Conversion 
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4.2.2 Concept of Pages 

In an extended memory system the 32K-word virtual address space is 
dividejd into eight sections called pages. Each page begins on a 4K word 
boundary, and the pages are numbered from through 7. A page is made up 
of units of 32 decimal words each. Since there can be as many as 128 of 
these units, a page can vary in siize from words to 4096 words, in 32-word 
increments. Figure 4-9 shows the virtual address space divided into eight 
4K-word pages. 

Figure 4-10 shows the virtual address space divided^nto five pages of vary- 
ing lengths. The shaded areas in the virtual address space are not part of 
the pages, and are therefore inticcessible. Thus, short pages cause gaps in 
the virtual address space. 



4.2.3 Relocation 

When the Memory Management Unit converts a 16-bit virtual address to 
an 18bit physical address, it relocates the virtual address. This means that 
two or more programs can have the same virtual addresses but different 
physical addresses. The Memory Management Unit relocates virtual ad- 
dresses in units of pages. It assigns a page to a section of physical memory 
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Figure 4-9: 4K-Word Pages 
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Figure 4-10: Smaller Pages 
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that starts on a 32-word decimal boundary. Figure 4-11 shows how the 
Memory Management Unit can relocate the virtual addresses of two dif- 
ferent programs. 

Figure 4-11: Relocation by Program 

PHYSICAL 
ADDRESS 
SPACE 



124K 



VIRTUAL 
ADDRESS 
SPACE 



VIRTUAL 
ADDRESS 
SPACE 



32K 



160000 



140000 



10K 




120000 



100000 



60000 



40000 



20000 



Program 1 in Figure 4-11 is relocated by 20000 octal. So, when program 1 
references virtual address 0, for example, it actually accesses memory loca- 
tion 20000. 

Since the Memory Management Unit relocates each page of virtual address 
space separately, a program c£in reside in disjoint sections of memory, as 
Figure 4-12 shows. 

4.2.4 Active Page Register (APR) 

The RT-11 monitor communicates with the Memory Management Unit 
through the Active Page Regist;ers, which are located in the I/O page. Each 
Active Page Register consists of two 16-bit words, as Figure 4-13 shows: a 
Page Address Register (PAR), and a Page Descriptor Register (PDR). 
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Figure 4-12: Relocation by Page 
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Figure 4-13: Active Page Register (APR) 
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The Page Address Register and the Page Descriptor Register always act as 
a pair. A set of eight Active Page Registers contains all the information 
necessary to describe and relocate the eight virtual address pages. The 
Page Descriptor Register describes how much of a virtual page to map to 
memory. The Page Address Register describes where in memory to put the 
virtual page. 
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The eight Active Page Registers are numbered from through 7. There is 
one Active Page Register for each page in the 32K-word virtual address 
space, as Figure 4-14 shows. 

Figure 4-14: Correspondence Between Pages and Active Page Registers 
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4.2.4.1 Page Address Register (PAR) — The eight Page Address Registers cor- 
respond directly to the eight virtual address pages. Bits through 11 of the 
Page Address Register contain the physical memory address in 32-word 
decimal units, or Page Address Field, for a particular virtual address page. 
Figure 4-15 shows the contents of the Page Address Register. Bits 12 
through 15 are reserved for future use by DIGITAL. 

Figure 4-15: Page Address Register (PAR) 
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4.2.4.2 Page Descriptor Register (PDR) — The Page Descriptor Register con- 
tains information about page expansion, page length, and access control for 
a particular page. Like the Page Address Registers, the Page Descriptor 
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Registers correspond directly to the virtual address pages, as Figure 4-14 
shows. Figure 4-16 shows the contents of the Page Descriptor Register. 
Unused bits are reserved for future use by DIGITAL. 

Figure 4-16: Page Descriptor Register (PDR) 
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In Figure 4-16, the field marked ACF represents the Access Control field. 
This field describes how a particular page can be accessed, and whether or 
not a particular access should cause an abort of the current operation. The 
values in this field are as follows: 

Value Meaning 

00 Nonresident page. Abort any attempt to access it. 

01 Resident read-only page. Abort any attempt to write into it. (RT-11 does 
not use this value.) 

10 Unused code. Abort all attempts to access this page. (RT-11 does not 
use this value.) 

11 Resident read/write page. All accesses are valid. 

The field marked ED is the Expansion Direction field. This bit indicates the 
direction in which a page can expand. The codes and their meanings are as 
follows: 

Value Meaning 

The page expands to higher addresses. (In RT-11, this field is always 0.) 

1 The page expands to lower addresses. (RT-11 does not use this value.) 

The field marked W is the Written Into field. It indicates whether the page 
has been modified since it was loaded into memory. (RT-11 does not use 
this field.) 

Some PDP-11 processors, instead of using bit 6 to indicate the page's 
modification status, use one or more of the reserved bits in the Page 
Descriptor Register. RT-11 ignores these other bits. 

The field marked PLF is the Page Length field. It indicates the length of a 
page, in 32-word decimal units. 

4.2.5 Converting a 16-Bit Address to an 18-Bit Address 

The information necessary for the Memory Management Unit to convert a 
16-bit virtual address to an 18-bit physical address is contained in the vir- 
tual address and in its corresponding Active Page Register set. Figure 4-17 
shows the meanings of the fields in the virtual address. These fields repre- 
sent a breakdown of the virtual address that is convenient for RT-11 and 
the MMU to use. 
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Figure 4-17: Virtual Address 
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Bits 13 through 15 of the virtual address constitute the Active Page Field. 
This field determines which Active Page Register the Memory Manage- 
ment Unit will use to create the physical address. 

Bits through 12 of the virtual address are the Displacement Field, which 
contains an address relative to the beginning of a page. 

The rest of the information necessary to create a physical address is con- 
tained in the Page Address field of the appropriate Page Address Register. 
Figure 4-18 shows how the Memory Management Unit converts a 16-bit 
virtual address to an 18-bit physical address. In this example, Page Ad- 
dress Register 6 contains 5460 octal, so virtual address 157746 converts to 
physical address 565746. 

As you can see from Figure 4-18, bits 13, 14, and 15 of the virtual address 
specify which Active Page Register to use. The Memory Management Unit 
adds the value in bits 6 throug'h 12 of the virtual address to bits through 



Figure 4-18: MMU Address Oonversion (Detail) 
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11 of the corresponding Page Address Register. The Memory Management 
Unit places the result of this addition in bits 6 through 17 of the physical 
address. The Memory Management Unit copies the value in bits through 
5 of the virtual address into bits through 5 of the physical address to form 
the final 18-bit physical address. 

4.2.6 Status Registers 

The Memory Management Unit also communicates with the RT-11 
monitor through two status registers. Status Register 0, located at 777572 
in the I/O page contains abort error flags, the memory management enable 
bit, and other essential information required by RT-11 to recover from an 
abort or to service a memory management trap. Status Register 2, located 
at 777576, is a read-only register containing the 16-bit virtual address that 
the Memory Management Unit is currently converting to an 18-bit physical 
address. (RT~11 does not use Status Register 2. However, if a memory 
management unit fault occurs in your system, you can examine this 
register yourself.) 

4.2.7 Kernel and User Processor Modes 

In addition to its primary function of managing the address space, the 
memory management system must provide some kind of protection for the 
monitor. To implement protection, the processor provides two modes of 
operation: kernel mode and user mode. The two modes provide a mechanism 
for separating system-level functions (kernel mode) from application-level 
functions (user mode). 

Each mode has its own set of eight Active Page Registers and its own stack 
pointer. Therefore, each processor mode also makes its own assignments of 
virtual addresses to physical locations: each mode has its own mapping. 
Figure 4-19 shows how the value in bits 14 and 15 of the Processor Status 
word determine in which processor mode execution takes place. 

Routines that run in kernel mode are generally part of the run-time 
operating system software and must not be corrupted by other programs. 
RT-11 uses the processor's kernel mode for the Resident Monitor and the 
USR, for interrupt service routines, and for device handlers, including 
.SYNCH and .FORK routines. Interrupts and traps vector through kernel 
mapping and cause execution to continue in kernel mode. 

Routines that run in user mode are generally part of appUcation programs. 
They are prevented from executing instructions that could corrupt the 
monitor or halt the computer. For example, a RESET instruction acts as a 
NOP instruction in user mode, and a HALT instruction generates a trap to 
10. RT-11 uses the processor's user mode for the Keyboard Monitor, for 
system utility programs, and for application programs and their completion 
routines. 
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Figure 4-19: Processor Status Word and Active Page Registers 
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Since each processor mode use« its own set of Active Page Registers, kernel 
mapping is not necessarily identical to user mapping. For example, if user 
virtual address 20010 is associated with physical address 40210, it does not 
necessarily mean that kernel virtual address 20010 is also mapped to 
physical address 40210. In fact, kernel virtual addresses are often mapped 
to different sections of physical memory from user virtual addresses. The 
mapping depends entirely on the contents of the Active Page Registers. 
Thus, changing from user to kernel processor mode has some interesting 
implications: referencing the s£ime virtual addresses in different modes can 
cause a program to access different physical locations. Figure 4-20 shows 
an example in which virtual address in kernel mode maps to physical loca- 
tion 0; in user mode, virtual address maps to physical location 500. This is 
the mapping scheme RT-11 uses for a virtual job at load time. 
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Figure 4-20: Mapping the Same Virtual Addresses to Different Physical 
Locations 
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4.2.8 Default Mapping 

Mapping is the process of associating virtual addresses with physical loca- 
tions (see Section 4.1.6). The RT-11 XM monitor manages the virtual ad- 
dress space by controlling the way the virtual addresses map to physical 
locations. The monitor does this by putting values into the Active Page 
Registers, thereby controlling the Memory Management Unit. 

When you first bootstrap an RT-11 extended memory system, kernel and 
user mapping are identical. That is, the monitor puts the same values into 
both the kernel and user sets of Active Page Registers. Table 4-1 shows the 
initial values of the Active Page Registers. Figure 4-21 shows the default 
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mapping that results from these values. Table 4-2 shows the default map- 
ping for a typical 4K virtual background job that has no extended memory 
overlays and no extra regions. 



Table 4-1: Initial Contents of Kernel and User APRs 
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Figure 4-21: Default Mapping at Bootstrap Time 
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Table 4-2: Initial Register Contents for Virtual Job 
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4.3 Software Concepts 



RT-ll implements support for extended memory through the extended 
memory, or XM, monitor. You must perform the system generation process 
to obtain an XM monitor, since it results from assembling the FB monitor 
source files with the conditional MMG$T set to 1. One of the major design 
considerations for RT-ll's extended memory support was that the XM 
monitor should closely resemble the FB monitor. 

In addition, you must use a special set of device handlers that can com- 
municate between a peripheral device and extended memory. It is part of 
the extended memory system design that all device handlers must be resi- 
dent in memory (you must load them with the monitor LOAD command) 
and that the USR must be permanently resident as well. 

The following sections describe the software concepts RT-ll uses in its ex- 
tended memory system. 

4.3.1 XM System Memory Layout 

Figure 4-22 illustrates the locations of the XM system components in 
physical memory. (Notice that this layout closely resembles the FB system 
arrangement described in Chapter 2.) When you first bootstrap an XM 
system, the system device handler and the Resident Monitor use the 
available memory just below the 28K-word boundary so that extended 
memory — the locations between 28K and 124K — is not used. Other loaded 
device handlers occupy the space below the Resident Monitor, followed by 
foreground and system jobs, if any, and the USR. 

The Resident Monitor executes in processor kernel mode and can access the 
low 28K words of memory and the I/O page. The USR also executes in 
kernel mode and is always memory resident in an XM system. The 
Keyboard Monitor executes in processor user mode, but since it is a 
privileged background job, it uses the same mapping as the Resident 
Monitor. (Privileged jobs are described in Section 4.3.3.2.) Physical loca- 
tions through 500 contain the vectors. 
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Figuire 4-22: XM System Meniiory Layout 
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4.3.2 How Programs Control Mapping 

Mapping — associating virtual addresses with physical locations — is the 
heart of the extended memory system. The XM monitor controls mapping 
by putting values into the Active Page Registers, thus controlling the 
Memory Management Unit. Obviously, this level of control is elementary 
and requires the monitor to keep close watch over the mapping situation. 

Fortunately, the monitor provides the means by which system and applica- 
tion programs can direct mapping operations and experience the benefits of 
accessing extended memory without concern for the specifics of the 
Memory Management Unit operations. In fact, your programs should never 
access the Active Page Registers or the Memory Management Unit Status 
Registers directly. Programs communicate their extended memory re- 
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quirements to the monitor through a collection of programmed requests. 
These requests store or modify information in data structures within the 
programs. Based on the contents of these data structures, the monitor 
modifies its own internal control blocks and puts the correct values into the 
Active Page Registers to perform the appropriate mapping action. 

In order to access extended memory, a program must: 

• Tell the monitor how much physical address space it needs. 

• Describe the virtual addresses it needs to the monitor. 

• Direct the monitor to associate the virtual addresses with the physical 
locations. That is, it must map the virtual addresses to the physical 
locations. 

Background, foreground, and system jobs can all access extended memory 
by following the three steps described above. Note, however, that none of 
the jobs can share physical address space with another job. 

The monitor and the programs use certain software concepts to describe the 
virtual addresses and the physical memory locations. The following sec- 
tions describe the concepts of physical address regions, virtual address win- 
dows, and the program's logical address space. 

4.3.2.1 Physical Address Regions — A program that needs to access extend- 
ed memory must communicate to the monitor a description of the physical 
memory locations it plans to use. The program does this by defining one or 
more regions in extended memory. 

A physical address region is a segment of physical memory consisting of 
contiguous 32-word decimal units. A region must begin on a 32-word boun- 
dary; it can be as large as 96K words. Your job can have as many as four 
regions at any time. The monitor assigns identification numbers to the 
regions when it creates them. A region identification is actually a pointer 
within your job's impure area to the start of the region's control block. (You 
will read more about region control blocks later.) 

The purpose of a region is to describe a portion of the physical address 
space, thus making it aveiilable for mapping and permitting a program to 
use those physical addresses. Sections of physical address space, if any, 
that are not part of a region are unavailable to a program. Figure 4-23 
shows how memory can be divided into regions. Note that two jobs cannot 
share a region in extended memory. 

Information about a physical address region is contained in a three-word 
data structure in your program, called a region definition block. The 
monitor collects information from the region definition block and stores it 
in a different internal data structure, called the region control block. The 
region control block is located in your program's impure area. Section 4.6 
provides more detailed information on the region definition and control 
blocks. 
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Figure 4-23: Physical Address Space and Two Regions 
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The Static Region 

The first region, called the static region, is created for a virtual job by the 
monitor at run time. (Section 4.3.3 describes the differences between virtual 
programs and privileged programs.) The size of the static region varies, 
depending on the size of the program and whether the program is a 
foreground or background job, tiut it is always within the low 28K words of 
memory. You can refer to the static region by using an identification of 0. 
Your program cannot eliminate the static region or change it in any way. 
(You cannot use the first region in privileged jobs, either; its data struc- 
tures are reserved and currently unused.) 
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The Dynamic Regions 

If your program needs to access more memory than the amount allocated at 
run time, it can create one to three dynamic regions and map virtual ad- 
dress windows to them. A dynamic region is a portion of physical memory 
above the 28K word boundary. The static region is created by the monitor 
and a program can create up to three more regions. A program can create 
and eliminate any of the dynamic regions. 

4.3.2.2 Virtual Address Windows — A program that needs to access extended 
memory must also communicate to the monitor a description of the virtual 
addresses it plans to use. While the monitor uses the concept of pages to 
describe virtual addresses to the Memory Management Unit, programs 
describe the virtual address space to the monitor by using the software con- 
cept of virtual address windows. 

A virtual address window is a section of the 32K-word virtual address space 
consisting of contiguous 32-word decimal units. A window, like a page, 
must begin on a 4K word boundary. However, unUke a pag6, whose max- 
imum size is 4K words, a window can be as large as 32K words and can en- 
compass one or more pages. There can be as many as eight virtual address 
windows or as few as one. The monitor assigns identification numbers to 
the windows when your program creates them. . 

The purpose of a window is to describe a section of virtual address space to 
the monitor, and thus permit a program to use those virtual addresses. Win- 
dows cannot overlap each other. (While a job can describe a new window 
that overlaps an existing one, the old one is eliminated when the new one is 
created.) And, sections of virtual address space, if any, that are not part of a 
window are not available for a program to use, unless the job is privileged. 
Each window that is less than 4K words causes a discontinuity in the pro- 
gram's virtual address space. A memory management fault results if the 
program tries to access a virtual address that does not fall within a mapped 
window. (A window is not useful until it is also mapped.) 

The monitor can assign physical addresses to the virtual addresses encom- 
passed by windows by calculating the number and size of the pages involv- 
ed and putting values into the corresponding Active Page Registers for 
those pages. Figure 4-24 shows how virtual address space can be divided 
into windows. 

Information about a virtual address window is contained in a seven-word 
data structure in your program, called a window definition block. The 
monitor collects information from the window definition block and stores it 
in a different internal data structure, called the window control block. The 
window control block is located in your program's impure area. Section 4.6 
provides more detailed information on the window definition and control 
blocks. 

The Static Window 

The first window, called the static window, is created for a virtual job by the 
monitor at run time. (Section 4.3.3 describes the differences between virtual 
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Figure 4-24: Virtual Address Space and Three Windows 
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jobs and privileged jobs.) The static window begins at virtual address 0, 
and its size is equal to the sizt! of your program's base segment, up to the 
program's high Umit. The static window contains your program's root, 
stack, virtual vectors, overlay handler, and low memory overlays. Instruc- 
tions, data, and buffers can appear in extended memory overlays or in ex- 
tended memory .SETTOP buffers; they are contained in a different window 
and region. You can refer to the static window by using an identification of 
0. Your program cannot eliminate the static window or change its mapping. 
(You cannot use the first window in privileged jobs, either; its data struc- 
tures are reserved and currently unused.) 

The Dynamic Windows 

If your program needs to access more memory than the amount allocated at 
run time, it can create one or more dynamic windows and map their virtual 
addresses to physical locations. The static window is created by the 
monitor and a program can create up to seven more windows. A program 
can create, eliminate, map, and remap any of the dynamic windows. 

4.3.2.3 Program's Logical Address Space (PLAS) — A program's logical ad- 
dress space is the range of physical address space effectively available to 
the program as a result of mapping operations. That is, all physical loca- 
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tions that are part of a region can be accessed by the program through map- 
ping operations, and are thus part of its logical address space. The Pro- 
gram's Logical Address Space is abbreviated as PLAS, a term often used to 
refer to extended memory support in general. 

4.3.3 Two Kinds of Mapping 

RT-ll provides two kinds of mapping for jobs that run in an extended 
memory environment: virtual mapping and privileged mapping. The follow- 
ing sections describe virtual jobs — those that run with virtual mapping — 
and privileged jobs — those that run with privileged mapping. 

4.3.3.1 Virtual Jobs — Jobs that run with virtual mapping execute in the 
processor's user mode. Virtual jobs do not use kernel mapping; virtual 
background jobs load into memory at an offset of 500. Virtual jobs cannot 
load over the USR, the Resident Monitor, or the I/O page. Virtual mapping 
is the better mapping mode to use for a job that does not require privileged 
access to the vector area, the monitor, or the I/O page, since it protects 
these system areas from virtual jobs. 

The first 500 bytes of each virtual job image are its virtual vector and 
system communication areas. The static window includes the virtual ad- 
dresses between the program's virtual address and its high Umit. The size 
of the static region varies depending on whether the virtual job is a 
foreground or a background job and on the size of the job. 

When you first run a vu-tual job, it can access only those virtual addresses 
that are within its own program bounds and that are also mapped to 
physical memory. However, a virtual job can use any remaining virtual ad- 
dress space between its own high Umit and the 32K-word address boundary. 
It can create one or more regions in extended memory, and one or more vir- 
tual address windows. It can then map a window to a region, thus accessing 
extended memory. If a virtual job unmaps a window, it cannot use the vir- 
tual addresses encompassed by the window unless it remaps the window. 
The virtual job can also use the extended memory .SETTOP feature and ex- 
tended memory overlays. 

Selecting Virtual Mapping 

You indicate that a job is to use virtual mapping by setting bit 10 of the Job 
Status Word before you run the program. If a particular job is always vir- 
tual, set bit 10 at assembly time. Use the following instructions to do this: 

.ASECT 
. = 44 

.WORD 2000 
.PSECT 

Or, if you prefer, select the program's mapping by running SIPP and patch- 
ing location 44 in the job's .SAV, .REL, or .SYS file before you run the 
program. 
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NOTE 

Do not change the valuei of bit 10 of the JSW when the pro- 
gram is running. Doing so interferes with accurate process- 
ing of I/O requests and can cause unpredictable results. 

A Virtual Background Job 

Use the monitor R command to start a virtual background job. The file 
should have the .SAV file tyjpe. A virtual background job loads into 
memory starting at physical location 500. Its highest physical address is 
equal to the size of the program in octal plus 500. 

The static region for a virtual b>ackground job begins at physical location 
500 and extends to the lowest address used by the USR. This prevents a 
virtual background job from ever accessing the physical vector area be- 
tween locations and 500. As a result, the vectors are protected from virtual 
jobs. Figure 4-25 illustrates the mapping for a virtual background job. 
Figure 4-26 shows how a virtual background job can map a window into the 
static region to use the available memory just below the USR. 

A Virtual Foreground or System Job 

Use the FRUN monitor commaiid to start a virtual foreground job and the 
SRUN command to start a virtual system job. You should link these jobs as 
background jobs with the .SAV file type, rather than as foreground or 
system jobs with the .REL or .SYS file types. You can FRUN or SRUN a 
virtual .SAV image because virtual foreground jobs require no relocation in- 
formation. Thus, the .SAV files are smaller on disk than .REL or .SYS files, 
and they load into memory faster.. 

When a foreground job is loaded, it uses the physical locations just below 
the lowest loaded handler or previously loaded system job. The USR slides 
down in memory, if necessary, to accommodate the foreground job. The 
foregiound job is linked with a default base address of 1000 (unless it is a 
.SAV image); its virtual addressies between and 500 represent the virtual 
vector and system communication areas. As with the background virtual 
job, the static window starts at virtual address and extends to this 
foreground program's high limit, rounded up to a 32-word multiple. 

The static region begins at physical location and extends to the program's 
physical high limit. The foreground impure area is located in physical 
memory just below the program. However, no virtual addresses are mapped 
to the impure area, so a virtual foreground job cannot access the contents of 
the impure area. As a result, tJie impure area is protected from a virtual 
foreground job. Figure 4-27 illustrates the mapping for a virtual 
foreground or system job. 

4.3.3.2 Privileged Jobs — The default mapping in an extended memory 
system is privileged. To indicate a privileged job, bit 10 of the Job Status 
Word remains 0. The XM environment appears to a privileged job to be 
very similar to an SJ or FB environment. A privileged job can access the 
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Figure 4-25: Virtual Background Job 
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low 28K words of memory as well as the I/O page. AU the RT-11 utility pro- 
grams run as privileged jobs in an extended memory environment. 

Privileged jobs, like virtual jobs, run in user processor mode. However, the 
monitor copies the contents of the kernel Active Page Registers into the 
user Active Page Registers. The default mapping for privileged jobs is thus 
the same as the default kernel mapping. 

Privileged jobs do have all 32K words of virtual address space available to 
them. But much of that virtual address space is already mapped to 
operating system software, the I/O page, and — in the case of a privileged 
foreground or system job — to a background job or the Keyboard Monitor. 
A privileged job can alter its default mapping through the use of extended 
memory overlays or programmed requests. It can map away all or part of 
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Figure 4-26: Virtual Background Job Mapping into the Static Region 
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the operating system to obtain a full 32K words of addressable memory for 
itself. For example, a program that needs to access the I/O page for only a 
limited time can explicitly map away from the I/O page when it is done us- 
ing it. 

Note that the static window and static region concept does not apply to 
privileged jobs. However, one virindow and one region are reserved by the 
monitor. Thus, privileged jobs have seven dynamic windows and three 
dynamic regions available to them, just as virtual jobs do. 

When a privileged job creates a window and executes the mapping pro- 
grammed requests, the default jsrivileged mapping for that virtual address 
space is temporarily unmapped. The monitor maps the window using the 
contents of the internal window control block to the new region of memory. 
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Figure 4-27: Virtual Foreground or System Job 
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When the privileged job unmaps the window, the monitor remaps that vir- 
tual address space according to the contents of the kernel Active Page 
Register set. This differs from a virtual job that unmaps a window, in which 
the virtual addresses encompassed by the window are unusable until the 
window is remapped. 

Since interrupt service routines execute in kernel mapping, privileged jobs 
containing user interrupt service routines should not change the mapping 
of interrupt service routines, the I/O page, or parts of the monitor during 
any time period in which an interrupt could possibly occur. The monitor 
depends on the fact that kernel and user mapping are identical when it ser- 
vices user interrupts. 
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Privileged Background Job 

Use the monitor R or RUN commands to start a privileged background job. 
Figure 4-28 illustrates the mapiping for a privileged background job. 



Figure 4-28: Privileged Backgiound Job 
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Privileged Foreground or System Job 

Use the monitor FRUN command to start a privileged foreground job. Use 
the SRUN command to start ei privileged system job. 
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Figure 4-29 illustrates the mapping for a privileged foreground or system 
job. 

4.3.3.3 Differences Between Virtual and Privileged Jobs — Table 4-3 sum- 
marizes the differences between virtual and privileged jobs. 



Figure 4-29: Privileged Foreground or System Job 
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4.3.3.4 Context Switching Between Virtual and Privileged Jobs — In an RT-11 
system with more than one job, the monitor saves job-dependent informa- 
tion when a new job replaces the one currently running. The monitor 
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Table 4-3: Comparison of Virtmal and Privileged Jobs 



Characteristic 



Virtual Job 



Privileged Job 



Value in bit 10 of JSW 

Original amount of ad- 
dress space available 



Amount of potential ad- 
dress space 



Benefits 



Starting procedure 



Static window 



Static region 



Possible number of 
windows 

Possible number of 
regions 



Accesses only the virtual 
addresses within its own 
program bounds. 

32K words. Creates win- 
dows to describe the vir- 
tual ctddress space be- 
tween its own high limit 
and the 32K word 
boundary. 



Provides protection for 
operating system software 
and other programs; takes 
minimal physical memory 
away from other jobs. 

BG: R command 

(.SIAV) 
FG: FRUN or SRUN 

(.IlEL, .SYS, .SAV; 

. SAV is recommended) 

Extends from program's 
virtual address to its 
high limit. 

BG: Extends from physi- 
cal location 500 to the 
lowest address used by the 
USR. 

FG: Extends from physi- 
cal location to the 
physical high limit of the 
job. 

7 plus the static window. 7 (1 window reserved) 





32K words. Accesses the 
low 28K words of memory 
plus the I/O page. 

32K words. If some por- 
tions of virtual address 
space are already in use 
(by a background job, for 
example), this job can un- 
map them and remap the 
addresses to memory 
above 28K words. It must 
leave certain areas map- 
ped whenever a user inter- 
rupt service routine could 
run. 

Compatible with FB and 
SJ systems. 



BG: R or RUN command 

(.SAV) 
FG: FRUN or SRUN 

(.REL, .SYS) 

None — all are dynamic. 



None — all are dynamic. 



3 plus the static region. 



3 (1 window reserved) 



restores this information when the original job executes again. This pro- 
cedure, called context switching, is described in detail in Section 3.4.2. 

In an XM system, each job in memory could be either a virtual or a privileg- 
ed job. The monitor, therefore, has more work to do when it switches con- 
text in an XM system. 
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When the monitor switches out the current job, it saves the information 
Ksted in Section 3.4.2. However, the monitor never saves the contents of the 
Active Page Registers that the current job uses. For this reason, your pro- 
grams should never manipulate the Memory Management registers direct- 
ly; their contents are lost during a context switch. The monitor also ignores 
a .CNTXSW programmed request if it occurs in a virtual job. The entire job 
is saved by the switch, and the virtual job is not permitted to access the 
vector area in any case. 

When the monitor switches in a new job, it assumes at first that the new job 
is privileged. It copies the contents of the kernel mapping registers into the 
user registers. The job can then access the low 28K words of memory plus 
the I/O page. Next, the monitor checks to see if the new job is the Keyboard 
Monitor. If it is, execution continues with no further modifications. 

If the new job is a privileged job, the monitor next checks the window and 
region control blocks in the job's impure area. If the job defined and map- 
ped one or more windows, the monitor restores the mapping based on the 
contents of the internal control blocks, thus altering the default privileged 
mapping for those windows. 

If the new job is virtual, the monitor clears the user mapping registers. 
Then it scans the window and region control blocks in the job's impure area. 
The monitor maps only the portion of the job's virtual address space that 
was defined in a window and mapped to a region at the time the job was 
switched out. Of course, any attempt to access an unmapped address 
causes a memory management fault. Unused portions of virtual address 
space remain unmapped unless the virtual job explicitly maps them. 

4.4 Typical Extended Memory Applications 

The following sections assume you understand the fundamental concepts of 
extended memory systems; they should help you see how to use extended 
memory. Some arrangements are suggested that may suit your own par- 
ticular situation. As you read, keep in mind what benefits you want from an 
extended memory system. In other words, why do you want to use it? 

4.4.1 Extended Memory Overlays 

The low 28K words of memory fill up rapidly with the Resident Monitor, 
device handlers, the USR, a foreground job, one or more system jobs, and a 
background job. To optimize use of this space and relieve the congestion, 
make the root segments of the foreground, system, and background jobs (if 
they are overlaid) as small as possible. Instead of segmenting the programs 
and using disk overlays though, you can put the overlays into extended 
memory. Make all the programs virtual jobs, unless they really need to ac- 
cess the monitor or the I/O page. 

The root segment can be minimal in size. All you need put there are queue 
elements, channels, interrupt service routines (if any — there are none in 
virtual jobs), and a JMP instruction to the first overlay. The overlay 
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segments can be permanently resident in extended memory to speed up 
execution. 

You can use the linker's /V opition to put your overlay segments into ex- 
tended memory. The Keyboard Monitor creates a region at run time, using 
information in the overlay handler and tables. The overlay handler creates 
and maps windows. Figure 4-30 shows a simple virtual background pro- 
gram that uses extended memory overlays. You can find detailed informa- 
tion on extended memory overlays in the RT-11 System User's Guide. 

Figure 4-30: Virtual Background Job with Extended Memory Overlays 
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4.4.2 Large Buffers or Arrays in Extended Memory 

In order to put a large buffeir or array into extended memory, you first 
create a region large enough to accommodate the array. Next, decide how 
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much virtual address space your program can commit to accessing the ar- 
ray and create a virtual address window of that size. Then simply write a 
subroutine that translates references to the array into instructions to 
remap the window into the correct part of the region. Figure 4-31 il- 
lustrates this situation. (The extended memory feature of the .SETTOP 
programmed request can create an extended memory buffer automatically. 
See Section 4.4.4 for information.) 

Figure 4-31: Virtual Background Job with an Array in Extended Memory 
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4.4.3 Multi-User Program 

An extended memory system is ideal for implementing a multi-user applica- 
tion. For example, you could develop a language interpreter that several 
programmers could use simultaneously. To implement this application, 
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separate your program into two sections: a pure code section that contains 
the interpreter, and a separate read/write work area for each user. Select 
part of your virtual address space to be the user scratch area, and create a 
window of that size. Next, decide how many users you want and create a 
region equal to the number of users times the size of the window. The inter- 
preter can change user context by remapping the window. Figure 4-32 
shows a multi-user program. 

Your multi-user program can use extended memory overlays. In this case, 
use one region for the overlays and one for the work areas. 



4.4.4 Work Space in Extended Memory 

Another application for you to consider is putting a work area into extend- 
ed memory instead of writing it to disk. 



Figuire 4-32: Multi-User Virtual Background Program 
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Consider how jobs in an FB system obtain the most space possible for dyna- 
mic buffering. A background job gets extra space by issuing a .SETTOP 
programmed request. It can obtain the space above the job image up to the 
top of the USR. To obtain extra space for a foreground job, you must 
allocate it with the FRUN/BUFFER:n command. Once the space is re- 
served by FRUN, the program can determine its size and claim it with a 
.SETTOP programmed request. In both cases, the extra space is within the 
28K words of low memory. 

In an XM system, extra space can be allocated from the physical space 
either above or below the 28K-word boundary. This feature can make jobs 
runnable that require too much memory for an unmapped RT-11 system. 
The ability to allocate extra space is most useful to virtual jobs because 
they can obtain space up to virtual address 177776 (32K words) by using 
the XM feature of the .SETTOP programmed request. All the memory ob- 
tained by .SETTOP is in extended memory; virtual foreground jobs do not 
require the FRUN/BUFFER:n command to allocate extra space. 

4.4.4.1 Enabling the XM Feature of the .SETTOP Programmed Request — There 
are two ways to enable the XM feature of the .SETTOP programmed re- 
quest. If your program has extended memory overlays, using the linker /V 
option to create them enables the XM .SETTOP programmed request 
automatically. It also enables the XM feature of the .LIMIT directive (see 
Section 4.4.4.4), links the extended memory overlay handler (VHANDL) 
into your job image, and establishes an extended memory overlay struc- 
ture. You use the /V option by issuing the LINK/PROMPT monitor com- 
mand, and then specifying /V on a subsequent command line. 

If your program has no overlays, or if it has only low memory overlays that 
you create with the linker 10 option, you enable the XM feature of the 
.SETTOP programmed request by using the LINK command with the /XM 
option. The /XM option enables the XM .SETTOP programmed request 
and the XM .LIMIT directive. It does not link the extended memory 
overlay handler into your job image, nor does it estabUsh an extended 
memory overlay structure for your program. 

For all programs, the .LIMIT directive returns as its high value the next 
available location for the job. The extra space your program obtains with 
.SETTOP in an extended memory system always begins at the octal ad- 
dress returned as the high value from the .LIMIT directive. This is true for 
all programs, whether or not they enable the XM feature of the .SETTOP 
programmed request. 

Section 4.4.4.3 describes how .SETTOP works when you execute a program 
in an extended memory environment without enabling the XM feature of 
.SETTOP. Section 4.4.4.4 shows how the XM feature of .SETTOP works 
after you enable it at link time; it also describes the XM feature of the 
.LIMIT directive. 

4.4.4.2 Program and Virtual High Limits and the Next Free Address — To under- 
stand XM .SETTOP, it is important that you understand the differences 
between the program high limit, the virtual high limit, and the next free ad- 
dress. Figure 4-33 shows a program's virtual address space. This program 
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has both low memory overlays created with the /O linker option, and ex- 
tended memory overlays created with the /V linker option. The program 
high limit is the highest virtual address used by the program's root seg- 
ment and its low memory (10) overlay regions, if any exist. The virtual high 
limit is the highest virtual address used by the extended memory (/V) 
overlay regions, rounded up to a 32-word decimal boundary, minus 2. (In 
octal, the low-order two digits of the address are always 76.) This is the 
value that prints on the link imap as nnnnnn, as the following example 
shows: 

Virtual high address = nnnnnn = ddddd. words, next free address = mmmmmm 

The linker has to calculate the value of the next free address. For a job that 
enables the XM feature of .SETTOP, it rounds up the virtual high limit to 
the next 4K-word boundary. The next free address, then, is the last word of 
the virtual address space encompassed by the highest Page Address 
Register used by the job, plus 2. It is always on a 4K-word boundary. (In oc- 
tal, the next free address is ahi^ays a multiple of 20000.) 



Figure 4-33: Program and Virtual High Limits, and the Next Free Address 
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As an example, consider a job with extended memory overlays whose vir- 
tual high limit is 55076. Its next free address calculated by the linker is 
60000, or the start of the next 4K words of virtual address space. This is the 
value that prints on the link map as the "next free address". The following 
example shows the values in our example situation: 

Virtual high address = 055076 = ddddd. words, next free address = 060000 

Of course, if a program has no extended memory overlays, it does not have 
a virtual high limit, and its program high limit is not rounded up. The link 
map for programs without overlays and for programs whose overlays were 
created solely by the /O option prints the program high limit as mmmmmm, 
as the following example shows. (The following line prints on all link maps, 
whether or not extended memory is present.) 

Transfer address = nnnnnn. High limit = mmmmmm =. ddddd. words 

4.4.4.3 Non-XM .SETTOP — If you do not enable the XM .SETTOP feature 
through the linker, using .SETTOP in an extended memory program has 
only limited value. 

For a privileged job that does not alter the default mapping, .SETTOP 
works the way it does in an ordinary SJ or FB system. If a privileged job 
creates a virtual address window and maps it to an extended memory 
region, the program high limit is not affected by the mapping. The value 
returned by .SETTOP still represents the highest address available to the 
program in the low 28K words of memory. 

When the monitor performs address checking for programmed requests, it 
looks first to see if the address (of an argument block, a data buffer, and so 
on) is entirely within a mapped dynamic window. If it is not, the monitor 
checks to see if the address is within the job's low memory area. If the ad- 
dress fails both these checks, a monitor error results and the job aborts. 

If the job is virtual, the program high limit at load time is set to the highest 
virtual address used by the root segment and any low memory {10) overlays. 
If your job performs its own mapping operations, they do not affect the pro- 
gram high limit as far as .SETTOP is concerned. So, the .SETTOP request 
is meaningless to these virtual jobs. The non-XM .SETTOP request deals 
exclusively with the low 28K words of memory. Virtual jobs use the proc- 
essor user mode and, therefore, are mapped according to the contents of the 
user Active Page Register set. The virtual job is prevented from accessing 
memory outside itself (because it is not mapped to any memory but its own 
dedicated physical space), so issuing a .SETTOP request in a virtual job 
without the LINK/XM command or the linker /V option does not obtain any 
extra memory. The value returned can be used by the virtual job to do its 
own mapping of the area available and then use it. 

When the monitor performs address checking for a virtual job, it ignores 
the program Mmits and simply checks to see that the virtual address is 
within a window that is currently mapped. If the address is not within a 
mapped window, a memory management fault results. 
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4.4.4.4 XM .SETTOP — When you enable the XM feature of .SETTOP, as 
Section 4.4.4.1 describes, .SETTOP becomes valuable to privileged and vir- 
tual jobs alike, although its value to privileged jobs is limited. 

For virtual jobs, not only does .SETTOP obtain virtual address space above 
the virtual high limit starting at; the program's next free address, but it also 
automatically maps the extra space to physical space. As a result, a job in 
an extended memory environraient can issue a .SETTOP programmed re- 
quest and obtain more usable virtual address space without concern for the 
details of managing extended memory. 

For privileged jobs, XM .SETTOP functions the way non-XM .SETTOP 
does, with the following exception: in privileged jobs, the XM .SETTOP 
request uses the new XM .LIMIT high value as the next free address, thus 
always returning the start of the buffer on a 4K-word boundary. A 
.SETTOP to any address belov^ this 4K-word boundary is not permitted. 

For both privileged and virtual programs, the Unker puts two words of in- 
formation into locations and 2 of the job image file. Location contains 
the Radix-50 code for VIR. Location 2 contains the value of the next free 
address minus 2, which can be significantly different from the virtual high 
limit. 

.LIMIT Directive 

For jobs in SJ and FB systems, and in XM systems without the XM feature 
of .SEITTOP, the .LIMIT MACRO directive returns two values to your pro- 
gram. These values are: 

• The lowest virtual address used by the program (usually 0) 

• The program high limit -H 2 (for example, 1644 -f- 2, or 1646) 

In XM programs that enable the XM feature of .SETTOP, .LIMIT returns 
a significantly different value: 

• The lowest virtual address used by the program (usually 0) 

• The next free address (always on a 4K-word boundary), which is usu- 
ally not equal to the program high limit + 2. 

Gaps in Virtual Address Space 

The linker always starts each extended memory (A^) overlay region at a 
4K-word boundary in your progiram's virtual address space. This restriction 
results from hardware requirements. Because of this there can be a gap be- 
tween the program high limit iind the start of the virtual overlay region. 
Your program causes an error if it attempts to reference the virtual ad- 
dresses within this gap. Similarly, any extra virtual address space that XM 
.SETTOP obtains for your program also starts on a 4K-word boundary. 
This means that a gap can exist between your program's virtual high limit 
and the start of the extra space. Your program cannot reference the ad- 
dresses within this gap. Figure 4-34 illustrates a typical program with both 
low memory (10) and extended memory (/V) overlays. 
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Figure 4-34: Gaps in Virtual Address Space 
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4.4.4.5 XM .SETTOP and Privileged Jobs — When a privileged job issues a 
.SETTOP request, if the next free address is above the base of the USR, the 
program is already using the virtual address space above the start of the 
monitor. Since there is no free memory that can be mapped starting at the 
program's next free address, the monitor cannot obtain any more space for 
this program. Thus, a privileged job can never obtain space above 
SYSLOW, the base of the USR. The .SETTOP request returns the value of 
the next free address minus 2 to location 50 in your program and to RO. This 
is the highest usable address. 

If there is memory available, the monitor tries to obtain it, basing the size 
of the area on the argument you specify with .SETTOP. The memory is 
always within the low 28K words. A privileged job can never obtain an 
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amount of virtual address space less than its own next free address minus 2. 
In addition, the next free address obtained with XM .SETTOP is always on 
a 4K-word boundary, and the job cannot issue a .SETTOP for any address 
below that. Therefore, the job loses the space between its last used address 
and the next 4K-word boundary. 

Privileged Background Jobs 

Figure 4-35 shows a privileged background job and all its Umits. When no 
foreground job is present in memory, the background job can obtain some 
space through .SETTOP. Often, there is still space available even when a 
foreground program is present. 

Privileged Foreground Jobs 

Since foreground jobs load into memory just below the last device handler 
and above the USR, there is no extra space available for them through a 
.SETTOP request. 

Figure 4-35: Privileged Background Job 
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Because of this situation, privileged foreground jobs are prohibited from us- 
ing extended memory overlays. This also means they cannot use the linker 
A^ option (either through LINK/FOREGROUND/PROMPT or through 
LINK/FOREGROUND/XM) to enable the XM feature of .SETTOP and 
.LIMIT. 

4.4.4.6 XM .SETTOP and Virtual Jobs — The monitor checks to see if there is 
some extended memory available. If the next free address is 200000, the 
program is already using the virtual address space controlled by Page 
Address Register 7. The request returns the value 177776 in location 50 and 
inRO. 

If .SETTOP can obtain virtual space starting with the next free address (on 
a 4K-word boundary), the monitor creates a region in extended memory for 
the necessary amount of space. If not enough space is available, the monitor 
creates as large a region as possible. (Be sure to check the value .SETTOP 
returns.) Then the monitor creates a window and maps it to the new region. 
It returns the new value of the highest available address in location 50 and 
in RO. If there is no space at all available, or if there are no region or window 
control blocks available, the request returns the value of the original 
highest available address in location 50 and in RO. 

So, for example, if you issue a .SETTOP request with an address argument, 
the monitor maps the virtual address space starting at the next 4K-word 
boundary above the program's virtual high limit, up to and including the 
address you specify. It maps so that the address specified is mapped, but 
up to 31 decimal additional words can also be mapped. 

If the address you specify in the .SETTOP request is below the highest 
used address, .SETTOP returns the value of the next free address minus 2 
in location 50 and in RO. The static window and virtual overlay regions 
created with the linker /V option cannot be eUminated by using an argu- 
ment to .SETTOP. 

Assuming your first .SETTOP succeeded and an extended memory region 
exists for your program, you can issue subsequent .SETTOP requests to 
control the region. Note, however, that you cannot create yet another region 
to obtain any more space. 

If the argument you specify in your next .SETTOP request is lower than 
the original next free address minus 2 from the link map, the monitor 
returns the old next free address minus 2 in location 50 and in RO and 
eliminates the region and window, if present (along with any data stored 
there). You can, of course, issue another .SETTOP later to create a new 
region again. You can also adjust the size of the buffer by remapping within 
the same region. 

To obtain a larger region, first issue a .SETTOP for a value below the cur- 
rent high limit, which eliminates the region and any data stored there. Then 
issue another .SETTOP for a larger value, which creates a new region. (Any 
data stored in the first buffer will be lost.) Note also that to ensure the in- 
tegrity of your data, only one window exists for the .SETTOP area in an ex- 
tended memory system. 
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To get less memory than a previous .SETTOP obtained, issue another 
.SETTOP with an address argiiment less than the first one but equal to or 
greater than the next free address. As a result, the size of the window still 
equals the size of the region, but a smaller amount of the window is mapped. 
This does not make any extended memory available for other users or other 
regions. 

Virtual Background Jobs 

Virtual background and foreground jobs are the most likely candidates for 
using the XM feature of the .SETTOP request. The request permits jobs to 
create large buffers in extended memory quickly and easily, which can help 
to reduce congestion in low memory. Figure 4-36 shows a virtual back- 
grouind job. 

Figure 4-36: Virtual Background Job 
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Virtual Foreground Job 

The .SETTOP request works in much the same way for foreground jobs as 
for background jobs. Fora virtual foreground job without the XM .SETTOP 
feature, the only extra space available is the space allocated through the 
FRUN/BUFFER:n command. For a job with the XM .SETTOP feature, the 
/BUFFER option is ignored. (The job cannot have buffers in both low and 
extended memory.) Figure 4-37 shows a virtual foreground or system job 
with a large buffer in extended memory. 

Figure 4-37: Virtual Foreground or System Job 
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4.4.4.7 Summary of .SETTOP Action — Figures 4-38 and 4-39 and Tables 4-4 
and 4-5 work together to summarize the results of all possible .SETTOP re- 
quests. In Figure 4-38, Job A is a background job whose next free address 
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is below SYSLOW, the base of the USE. Job B is a background job whose 
next free address is above SYSLOW. (In the table, next free address is ab- 
breviated to NFA.) The values in parentheses represent specific ranges for 
.SETTOP arguments. 



Figure 4-38: Background .SETTOP Summary 
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Table 4-4: Background .SETTOP Summary 



.SETTOP Virtuall Job Privileged Job 

Argument Non-XM .SETTOP XM .SETTOP Non-XM .SETTOP XM .SETTOP 
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Table 4-4: Background .SETTOP Summary (Cont.) 



.SETTOP Virtual Job Privileged Job 

Argument Non-XM .SETTOP XM .SETTOP Non-XM .SETTOP XM .SETTOP 



High Limit for Job B After .SETTOP 

(1) 
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* If available; otherwise, as much extended memory as possible is obtained for the .SETTOP region. 



Figure 4-39: Foreground .SETTOP Summary 
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Table 4-5: Summary of Foreground Job High Limit After .SETTOP 
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4.4.5 Plan Your Own Application 

When you plan your own esitended memory application, decide first 
whether the semi-automatic ways of using extended memory are useful to 
you. If the XM .SETTOP feature is all you need, your program will be fairly 
simple to write. Similarly, if you can easily segment your program into 
overlays, using the extended memory (/V) overlay feature of the linker may 
be simple for you. If you decide to handle the mapping yourself in a 
MACRO- 11 program, sketch out diagrams ahead of time showing the ar- 
rangements of the system corciponents, handlers, and other jobs. Unless 
your job needs to access the monitor routines or the I/O page, make it a vir- 
tual job. Think about the number of windows and regions you need and 
design the program accordingly . The following sections provide detailed in- 
formation about the programmed requests and macro calls that a 
MACRO- 11 program in extended memory can use, as well as information 
about extended memory restrictions. 

4.5 Introduction to the Extended Memory Programmed Requests 

It is not difficult to access es:tended memory in a MACRO-11 program 
throtigh the programmed requests, once you understand the general pro- 
cedures you must follow and the tools RT-11 provides. Essentially, if your 
program does its own management of extended memory (rather than rely- 
ing on any of the semi-automatic means described in the previous section), 
you must first establish window and region definition blocks. Next, you 
must specify the amount of physical memory the program requires, and 
describe the virtual addresses you plan to use. Do this by creating regions 
and windows. Then, associate virtual addresses with physical locations by 
mapping the windows to the regions. You can then remap a window to 
another region or part of a rej^on. You can also eliminate a window or a 
region. In any case, once the initial data structures are set up, you can 
manipulate the mapping of windows to regions to suit your needs. 

Table 4-6 summarizes the actions a program that uses extended memory 
may need to take. It also Usts the appropriate procedures for the program 
to follow. FamiUarize yourself with the procedures and the corresponding 
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programmed requests and macro calls. TheRT-11 Programmer's Reference 
Manual provides detailed information on the format of each programmed 
request and macro call. Study this information before you attempt to write 
an extended memory program. 



Table 4-6: Summary of Activities for a Program in an Extended Memory 
System 



Activity 



Procedure to Follow 



Define offsets and symbols for 
a region definition block. 

Set up a region definition block 
and specify the region size. 

Create a region. 

Confirm the status of the new 
region. 



Define offsets and symbols for 
a window definition block. 

Set up a window definition 
block and describe the window. 

Create a window. 

Confirm the status of the new 
window. 



Associate a window with a par- 
ticular region as preparation for 
mapping the window. 

Map a window to a region 
(explicitly). 

Map a window to a region 
(implicitly). 



Obtain the current mapping 
status of a particular window. 

Unmap a window (explicitly). 

Unmap a window (impUcitly). 



Eliminate a window. 
Eliminate a region. 



Use the .RDBDF or .RDBBK macro. 



Use the .RDBBK macro. 



Use the .CRRG programmed request. 

Examine the contents of the region definition block 
after you use the .CRRG request to create the region. 
(Check the status bits in the status word.) 

Use the .WDBDF or .WDBBK macro. 



Use the .WDBBK macro. 

Use the .CRAW programmed request. 

Examine the contents of the window definition block 
after you use the .CRAW request to create the window. 
(Check the status bits in the status word.) 

Move the region identification from R.GID in the 
region definition block to W.NRID in the window 
definition block. 

Use the .MAP programmed request. 

Set WS.MAP in the window definition block and load 
W.NRID before you issue the .CRAW request to create 
the window. This procedure creates the window and 
then maps it to a region. 

Use the .GMCX programmed request. 

Use the .UNMAP programmed request. 

Use the .MAP programmed request to map the window 
elsewhere. 

You can also unmap a window by eliminating the 
region to which it is mapped, or by eliminating the win- 
dow itself. 

Use the .ELAW programmed request. 

Use the .ELRG programmed request. 
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4.6 Extended Memory Data Structures 

A program in an extended memory environment communicates with the 
monitor through special data «tructures. For each region it defines, a pro- 
gram contains one region definition block to describe the size of the extend- 
ed memory region. The monitor also maintains a set of internal data struc- 
tures. The region control block, located in the job's impure area, describes a 
region. The monitor can maintain up to four region control blocks per job. 
For each window it defines, 8i program also uses one window definition 
block to describe the virtual addresses encompassed by that window. The 
window control block, located in the job's impure area, is the monitor's in- 
ternal description for a window. The monitor can maintain up to eight win- 
dow control blocks. The I/O queue element contains extra information in an 
extended memory system. Finally, the monitor allocates regions in extend- 
ed memory based on its internal free memory list. 

The following sections descrilbe these data structures and show, where 
necessary, how to create them. 

4.6.1 Region Definition Blocit 

A region definition block is a three-word area in your program that contains 
information about a region you define in extended memory. The monitor 
uses the region definition block to communicate with your job when you 
issue a .CRRG or .ELRG programmed request. You must set up the region 
definition block in your program and define its symbolic offsets before you 
can create a region in extended memory. You must then place the region's 
size in the region definition block. After you create the region, the monitor 
returns its identification and some status information to you through the 
region definition block. Each time your program needs to refer to this 
region, it uses the region identification. (Since the monitor creates the static 
region for you, you do not know its identification. You can always refer to 
the static region by using as its identification.) Figure 4-40 and Table 4-7 
show the structure of a region definition block. 

Figure 4-40: Region Definition Block 



R.GID 



R.GSIZ 



R.GSTS 



4.6.1.1 Region Status Word — The region status word contains information 
on the status of a region. Table 4-8 shows the bits in the region status word 
and their meaning. Bits tllirough 12 are reserved for future use by 
DIGITAL. 
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Table 4-7: Region Definition Block 

Symbol Modifier 



Byte 
Offset 



Contents 







R.GID 



R.GSIZ 



R.GSTS 



Monitor's 
routine 



CRRG 



.RDBBK macro 
or user program 

Monitor's .CRRG 
routine 



A unique region identification. Use it 
later to reference this region. Tlie region 
identification is actually a pointer within 
the job's impure area to the region con- 
trol block. The identification for the 
static region in a virtual job is 0. 

The size of the region you need, in 
32-word decimal units. 

The region status word. 



Table 4-8: Region Status Word 

Bit Name Bit Pattern 



Meaning When Set 



15 RS.CRR 



14 RS.UNM 



13 RS.NAL . 



100000 The monitor created this region suc- 

cessfully. The .CRRG routine sets this 
bit; the .ELRG routine clears it. 

40000 One or more windows were unmapped as 

a result of eliminating this region. The 
.ELRG routine sets this bit when 
necessary. 

20000 Not currently used, but reserved. 



4.6.1.2 .RDBDF Macro — Use the .RDBDF macro to define symbols for the 
region definition block (see the description of .RDBBK in Section 4.6.1.3). It 
defines the symbolic offset names for the region definition block and the 
names for the region status word bit patterns. In addition, this macro 
defines the length of the region definition block by setting up the following 
symbol: 

F^.GLGH = 6 

Note that this macro does not reserve space for the region definition block. 
The format of the .RDBDF macro is as follows: 

.RDBDF 

The .RDBDF macro expands as follows: 



R.GID 


= 


R.GSIZ 


= 2 


R.GSTS 


= 4 


R.GLGH 


= 6 


RS.CRR 


= 100000 


RS.UNM 


= 40000 


RS.NAL 


= 20000 
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4.6.1.3 .RDBBK Macro — The .RDBBK macro (like the .RDBDF macro) 
defines symbols for the region definition block. This macro also actually 
reserves space for it (unlike the .RDBDF macro). You specify as the argu- 
ment to this macro the size of the region you need. If you use .RDBBK you 
need not use .RDBDF, since .RDBBK automatically invokes .RDBDF. 

The format of the .RDBBK macro is as follows: 

.RDBBK rgsiz 

rgsiz is the size of the dynamic region, expressed in 32-word decimal units. 

The following example uses thes .RDBBK macro to create a region definition 
block for a region 4K words in size. (4K words is equivalent to 200 32-word 
units.) Then it creates the region. 

RGADR: .RDBBK #200 

.CRRG #ARGBLK,#RGADR ;CREATE REGION 

See Section 4.10 for an example program that uses .RDBBK. 

4.6.2 Region Control Block 

A region control block is a three-word area in your job's impure area whose 
contents are maintained by th€! monitor. A virtual job dedicates one region 
control block to the static region. For a privileged job, one region control 
block is reserved by the monitor and cannot be used by a program. Thus, all 
jobs can have up to three dynamic regions whose status is maintained by 
the monitor in the region control blocks. 

Figure 4-41 and Table 4-9 show the structure of a region control block. The 
.ELRG programmed request clears all its fields. 

Figure 4-41: Region Control Block 



R.BADD 


R.BSIZ 


R.BMWD 


R.BSTA 



4.6.3 Window Definition Block 

A window definition block is a seven-word area in your program that con- 
tains information about a virtual address window you define. The monitor 
uses the window definition block to communicate with your program when 
you issue a .CRAW, .ELAW, .GMCX, or .MAP programmed request. You 
must set up the window definition block in your program and define its 
symbolic offset names before you can create a virtual address window. You 
must then place a description of the window you need in the window defini- 
tion block. After you create the window, the monitor returns its identifica- 
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Table 4-9: Region Control Block 



Byte 

Offset Symbol 



Modifier 



Contents 



R.BADD Monitor's .CRRG 

routine 

2 R.BSIZ Monitor's .CRRG 

routine 

4 R.BSTA The monitor at run 

time; the monitor's 
.CRRG routine clears 
this byte 



The starting address of the region, 
expressed in 32-word units. 

The size of the region in 32-word 
units. If this word is 0, this region 
control block is free. 

This byte is always clear unless 
the region was created by an XM 
.SETTOP. The monitor then sets 
bit 1, called R.STOP. 



R.BNWD Monitor's .CRRG 
routine clears this 
byte; .MAP incre- 
ments it; .UNMAP 
decrements it 



The number of windows currently 
mapped to this region. 



tion and some status information to you through the window definition 
block. Figure 4-42 and Table 4-10 show the structure of a window defintion 
block. 



Figure 4-42: Window Definition Block 



W.NAPR 



W.NID 



W.NBAS 



W.NSIZ 



W.NRID 



W.NOFF 



W.NLEN 



W.NSTS 



4.6.3.1 Window Status Word — The window status word serves a dual pur- 
pose. First, it allows the .CRAW request to create a window and map it to a 
region in one step when you put a value of 1 in bit 8. Second, the window 
status word allows the monitor to communicate status information to your 
program. Table 4-12 shows the bits in the window status word and their 
meaning. Bits through 7 and 9 through 12 are reserved for future use by 
DIGITAL. 
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Table 4-10: Window Definition Block 

Symbol Modifier 



Byte 
Offset 



Contents 



W.NID 



W.NAPR 



W.NBAS 



W.NSIZ 



W.NRID 



10 



W.NOFF 



12 



W.NLEN 



Monitor's .CEAW 
routine 



.WDBBK macro; 
monitor's .GMCX 
routine 



Monitor's .CH,AW and 
.GMCX routines 



.WDBBK macro; 
monitor's .GMCX 
routine 

.WDBBK macro; 
monitor's .GMCX 
routine 



.WDBBK maciro; 
monitor's .GMCX 
routine 



.WDBBK macro; 
monitor's .MAP and 
.GMCX routines 



A unique window indentification. 
Remember that you can always 
refer to the static window by using 
as its identification. 

The number of the Active Page 
Register that includes the 
window's base address. Remember 
that a window must start on a 
4K-word boundary. See Table 4-11 
for the correspondence between 
Active Page Registers and virtual 
addresses. For privileged jobs, the 
vahd range of values is from to 7. 
For virtual jobs, the new window 
must not overlap the static win- 
dow. You can find the lowest valid 
value for W.NAPR by issuing a 
.GMCX request for the static win- 
dow, converting the high virtual 
address to an APR value, and in- 
crementing it. 

The base virtual address of this 
window. This value should in- 
dicate the same address as 
W.NAPR. It is provided as a 
validity check. Note that it is ex- 
pressed as an octal address, not in 
32-word decimal units. 

The size of this window, expressed 
in 32-word units. 



Identification of the region to 
which this window maps. The 
.GMCX request returns a if the 
window is not mapped. Otherwise, 
it returns the identification of the 
region to which it is mapped. Note 
that the value is also if the win- 
dow is mapped to the static region. 

The offset, expressed in 32-word 
decimal units, into the region at 
which to start mapping this win- 
dow. The .GMCX request clears 
this word if the window is not map- 
ped; otherwise, it puts the offset 
value here. 

The amount of this window to 
map, expressed in 32-word units. 
If you put here (or .CRAW with 
WS.MAP set), .MAP maps as 
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Table 4-10: Window Definition Block (Cont.) 

Byte 
Offset Symbol Modifier Contents 



much of the window as possible. 
On successful completion of the 
mapping operation, .MAP puts 
the actual length it mapped in 
W.NLEN. If you put a value here 
(other than 0), .MAP does not 
change it. The .GMCX request 
clears this word if the window is 
not mapped; otherwise, it puts the 
actual length mapped here. 

14 W.NSTS .WDBBK macro; The window status word. The 
monitor's .CRAW, .GMCX request clears this word if 
.ELAW, and .GMCX the window is not mapped; other- 
routines wise, it sets WS.MAP to 1. 



Table 4-11: Correspondence Between Active Page Registers and Virtual 
Addresses 

Virtual Address Range Active Page Register Number 

0-17776 

20000-37776 1 

40000-57776 2 

60000-77776 3 

100000-117776 4 

120000-137776 5 

140000-157776 6 

160000-177776 7 



4.6.3.2 .WDBDF Macro — Use the .WDBDF macro to define symbols for the 
window definition block (see the description of .WDBBK in Section 4.6.3.3). 
It defines the symbolic offset names for the window definition block and the 
names for the window status word bit patterns. In addition, this macro also 
defines the length of the window definition block by setting up the follow- 
ing symbol: 

W.NLGH = 16 

Note that the .WDBDF macro does not reserve any space for the window 
definition block. 

The format of the .WDBDF macro is as follows; 

.WDBDF 
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Table 4-12: Window Status \^^ord 
Bit Name Bit Pattern 



Meaning When Set 



8 



WS.MAP 



13 



14 



WS.ELW 



WS.UNM 



15 



WS.CRW 



400 The .CRAW request should also map the new 

window in addition td creating it. Set this bit 
in the window definition block by specifying it 
in the .WDBBK macro. Be sure to load 
W.NRID before using .CRAW. 

20000 The monitor eliminated one or more windows 

as a result of the current operation. The 
.CRAW and .ELAW routines can set this bit. 

40000 The monitor unmapped one or more windows 

as a result of the current operation. The 
.CRAW and .ELAW routines can set this bit. 
The .MAP and .UNMAP routines set or clear 
this bit, as required. 

100000 The monitor created this window successfully. 

The .CRAW routine sets this bit; the .ELAW 
routine clears it. 



The .WDBDF macro expands as follows: 



W.NID 


= 


W.NAPR 


= 1 


W.NBAS 


= 2 


W.NSIZ 


= 4 


W.NRID 


= 6 


W.NOFF 


= 10 


W.NLEN 


= 12 


W.NSTS 


= 14 


W.NLGH 


= 16 


WS.CRW 


= 100000 


WS.UNM 


= 40000 


WS.ELW 


= 20000 


WS.MAP 


= 400 



4.6.3.3 .WDBBK Macro - The .WDBBK macro (like the .WDBDF macro) 
defines symbols for the window definition block. This macro also actually 
reserves space for it (unlike the .WDBDF macro). The macro permits you to 
specify enough information about the window to simply create it. Or you 
can use the optional arguments to provide more information in the window 
definition block. The extra information allows you to create a window and 
map it to a region by issuing just the .CRAW programmed request. If you 
use .WDBBK you need not use .WDBDF, since .WDBBK automatically in- 
vokes .WDBDF. 

The format of the .WDBBK macro is as follows: 

.WDBBK wnapr,wnsiz[,wnrid,wnoff,wnlen,wnsts] 

wnapr is the number of the Active Page Register set that includes the win- 
dow's base address. Remember that a window must start on a 4K-word 
boundary. See Table 4-11 for the correspondence between Active Page 
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Registers and virtual addresses. The valid range of values is from 
through 7. 

wnsiz is the size of this window. Express it in 32-word decimal units. 

wnrid is the identification for the region to which this window maps. This 
argument is optional. It is usually filled in at run time, rather than at 
assembly time. 

lonoff is the offset into the region at which to start mapping this window. 
Express it in 32-word decimal units. This argument is optional; supply it if 
you need to map this window. The default is 0, which means that the win- 
dow starts mapping at the region's base address. 

wnlen is the amount of this windoW to map. Express it in 32-word decimal 
units. This argument is optional; supply it if you need to map this window. 
The default value is 0, which maps as much of the window as possible. 

wnsts is the window status word. This argument is optional; supply it if you 
need to map this window when you issue the .CRAW request. Set bit 8, call- 
ed WS.MAP, to cause .CRAW to perform an implied mapping operation. 

The example in Figure 4-43 uses the .WDBBK macro to create a window 
definition block. First it establishes a convention for expressing K-words in 
units of 32 decimal words each. Then it defines the window definition block, 
creates the window, and maps the window to a region. 

The macro call sets up a window definition block for a window that is 2K 
words long. The window begins at address 120000, so Active Page Register 
set 5 controls its mapping. The .CRAW request to create this window will 
also map it to an area in extended memory. The window will map to the 
region starting 2K words from the beginning of the region, and the .CRAW 
request will map as much of the window as possible. Note that the program 
must move the region identification into this block to select the correct 
region before it issues the .CRAW request. 

Figure 4-43: .WDBBK Macro Example 

.MAIN. MACRO V04.00 16-0CT-79 16: 14 : 25> PAGE 1 

I .HCALL .WDBBK) .RDBBKr.CRRGf. CRAUf. EXIT 

2 

3 000040 KMMU = 1024. /32. SSIZE IN 32. WORD 

4 (UNITS 

5 000000 START! .CRR6 *AREA»*RGADR iCREATE A REGION 
6 

7 f 

8 ) 

9 ! . 
10 

11 000020 016767 MOV RGADR+R.6ID» WNADR+W.NRID JMOVE REGION 

000024 
000036 

12 JID TO WINDOW DEFl- 

13 JNITION BLOCK 

14 000026 .CRAU tAREArtUNADR (CREATE WINDOW AND 

15 (MAP IT 
16 

17 ( 

18 ( 
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Figure 4-43: .WDBBK Macro Example (Cont.) 



19 






20 






21 


000046 




22 






23 






24 


000050 






000050 


000000 




000052 


000100 




000054 


000000 


25 






26 


000056 






000056 


000 




000057 


005 




000060 


000000 




000062 


000100 




000064 


000000 




000066 


000100 




000070 


000000 




000072 


000400 


27 






28 






29 


000074 




30 




000000 



RGADR! 



UNADR! 



, EXIT 



AREA! 



.LIST 


MEB 


<RDBBK 


2*KMMU 


.WORD 




,UORIl 


2*KMMU 


.WORD 




. UIiBBK 


5»2*KM 


,BYTE 




.BYTE 


5 


,WORC 




.WORD 


2*KMMU 


.WORD 




.UORD 


2*KMMU 


,UORB 





. UORB 


US. HAP 


.BLKU 


2 


, ENB 


START 



iEXIT PROGRAM 



rCREATE REGION DEFI- 



JNITION BLOCK 
5»2*KMMUj j2*KMhU>0>US.MAP (CREATE 



rWINDOW DEFINITION 

!BLOCK 

!EMT AREA 



4.6.4 Window Control Block 

The window control block is a seven- word area in your job's impure area 
whose contents are maintained by the monitor. A virtual job dedicates one 
window control block to the static window. For a privileged job, one window 
control block is reserved by the monitor and cannot be used by a program. 
Thus, all jobs can have up to seven dynamic windows whose status is main- 
tained by the monitor in the window control blocks. Figure 4-44 and Table 
4-13 show the structure of a window control block. 



Figure 4-44: Window Control ISlock 



W.BRCB 



W.BLVR 



W.BHVR 



W.BSIZ 



W.BOFF 



W.BNPD 



W.BFPD 



W.BLPD 



4.6.5 I/O Queue Element 

The I/O queue element in an extended memory system is ten words long, 
rather than seven words long as it is in FB and SJ systems. Section 7.9.3 
describes the XM I/O queue element in detail. 
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Table 4-13: Window Control Block 




Byte 
Offset Symbol 


Modifier 


Contents 


W.BRCB 


Monitor's .MAP 
routine; the .UNMAP 
request clears it 


A pointer to the region control 
block of the region to which this 
window is mapped. If the value is 
0, the window is not mapped. 


2 W.BLVR 


Monitor's .CRAW 


The window's low virtual address 




routine 


limit. 



4 W.BHVR Monitor's .MAP 
routine 



The window's high virtual address 
hmit. 



W.BSIZ Monitor's .CRAW 
routine; the .ELAW 
request clears it 



The window's size, in 32-word 
decimal units. If the value is 0, 
this window control block is free. 



10 W.BOFF Monitor's .MAP 
routine 

12 W.BFPD Monitor's .CRAW 

routine 

13 W.BNPD Monitor's .MAP 

routine 

14 W.BLPD Monitor's .MAP 

routine 



The offset into the region at which 
this window begins to map, in 
32-word decimal units. 

The low byte of the address of the 
first Page Descriptor Register 
that affects this window. 

The number of Page Descriptor 
Registers that affect this window. 

The contents of the last Page 
Descriptor Register that affects 
this window. 



4.6.6 Free Memory List 

The monitor maintains a data structure called the free memory list, which it 
uses to allocate areas of extended memory. The list consists of a table of 10 
decimal doublewords. The address of the top of the table is $XMSIZ, and 
the table is located in p-sect XMSUBS. The high-order word of each word 
pair indicates the size of an available area in extended memory, expressed 
as a number of 32-word decimal units. The low-order word of the pair con- 
tains the address of the area, divided by 100 octal. A value of» - 1 ends the 
table. 

At bootstrap time, the table contains only one entry. The high-order word of 
the pair contains the total amount of extended memory. The low-order word 
contains the value 1600. When a job requests an extended memory region, 
the monitor searches through the table for an area large enough to meet the 
request. It returns the area in extended memory that meets the size require- 
ment and has the lowest starting address. The monitor reduces the amount 
of memory in the first doubleword of the free memory list, and adjusts its 
starting address. 
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The other nine words of the free memory list are used when jobs return 
areas of extended memory to the available pool. In a very active system, the 
extended memory area can become quite fragmented. 



4.7 Flow of Control Within Each Programmed Request 

This section summarizes the activities that take place internally for each 
progi'ammed request your program can issue. Consult the RT-11 Program- 
mer's Reference Manual for the detailed syntax of each request. 



4.7.1 Creating a Region: .CI^RG 

Issue the .CRRG programmed request to create a region in physical ad- 
dress space. 

The monitor's .CRRG routine first checks R.GSIZ in the region definition 
block to make sure that you have requested a region with a valid size. (The 
size must be between 1 and 96K.) If the size is invalid, the request returns 
with error code 10 in byte 52. 

Next, the routine looks for a frtie region control block. The request returns 
with error code 6 in byte 52 if no region control blocks are free. 

The routine attempts to allocate the appropriate amount of memory for the 
region, based on the amount you specified in the programmed request. To 
get the most memory possible, ask for 96K words. The routine scans the 
free memory list for a region with the correct size. The request returns with 
error code 7 in byte 52 if it cannot allocate a region with the size you re- 
quested. In addition, RO contains the largest amount of memory available. 
Issue the .CRRG request again for this amount of memory. If this second 
request fails, it means that some other job in the system just acquired some 
of the memory. Continue to reissue the .CRRG request with the new value 
from RO until you finally obtaiiti a region. 

The request succeeds when th<; monitor allocates the region. The routine 
puts the region identification into R.GID in the region definition block. It 
sets RS.CRR in the region status word; it clears R.BSTA and R.BNWD in 
the region control block, and iit puts values into R.BADD and R.BSIZ, 
which are also located in the region control block. The memory obtained is 
then removed from the monitor's free memory list and reserved for your j ob. 



4.7.2 Creating a Window: .CRAW 

Issue the .CRAW programmed request to create a virtual address window. 

First, the monitor's .CRAW routine checks W.NAPR in the window defini- 
tion block for a valid value. The request returns with error code in byte 52 
if the number of the Active Page Register set is invalid for any reason. 

Next, the routine shifts W.NAPR to set up the window's base address in 
W.NBAS, which is also located in the window definition block. 
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The routine then checks W.NSIZ in the window definition block to make 
sure that you requested a valid size for the window (the window cannot ex- 
ceed the 32K-word boundary). If there is any problem with the size, the re- 
quest returns with error code in byte 52. 

The routine clears bits WS.ELW, WS.UNM, and WS.CRW in the window 
status word. 

The next check is to see if the new window will overlap with an existing win- 
dow. If the job is a virtual job and the new window overlaps with the static 
window, the request returns with error code 0. In all other situations where 
the new window overlaps an existing window, the routine eUminates the ex- 
isting window. If the existing window is mapped, the routine unmaps it. 
The .CRAW routine sets WS.ELW in the window status word if it 
eUminates a window to create the new one. It sets WS.UNM if it also un- 
maps a window as it eliminates it. 

Next, the routine looks for an available window control block. The request 
returns with error code 1 if there are no free window control blocks. 

The request succeeds when the monitor modifies the appropriate data 
structures. It puts values in W.BSIZ, W.BLVR, and W.BFPD in the win- 
dow control block; it puts the window identification in W.NID in the win- 
dow definition block, and it sets WS.CRW in the window status word. 

If WS.MAP in the window status word was set when you issued the 
.CRAW request, the routine now maps the window to the region whose 
identification is stored in the window definition block. To do this, the 
routine follows the steps outlined in the .MAP programmed request. 

4.7.3 Mapping a Window to a Region: .IVIAP 

Issue the .MAP programmed request to map a virtual address window to a 
physical address region. The window definition block must contain the iden- 
tification of the region to which the window will map. 

First, the monitor's .MAP routine finds the window control block that cor- 
responds to the window you specify in the request. It checks W.NID to do 
this, and returns with error code 3 if the value is or not valid. 

Next, the routine finds the region control block for the region to which this 
window wiU map. The request returns with error code 2 if the region iden- 
tification is invalid for any reason. 

The routine looks at the offset into the region at which the window is to 
begin mapping. This value is contained in W.NOFF in the window defini- 
tion block. If the offset is beyond the end of the region, the request returns 
with error code 4. 

The routine checks the length of the window it is to map. This value is con- 
tained in W.NLEN in the window definition block. If the value is 0, the 
routine picks up the size of the region from the offset value to the end of the 
region. If this amount of memory is bigger than the window, the routine 
reduces the amount until it equals the window size, which it stores in 
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W.NLEN. Note that if you put into W.NLEN, the value that is there after 
the .MAP request executes is not 0, but is instead the actual length of the 
window that was mapped. 

If the value of W.NLEN is not at the start of the .MAP routine, it in- 
dicates the explicit length of the window to map. If the value is larger than 
the window size, or if the window would extend beyond the bounds of the 
region, the request returns with error code 4. 

The routine increments R.BNWD in the region control block, which main- 
tains a count of the number of windows mapped to this region. 

If this window is already mapped elsewhere, this routine unmaps it and sets 
WS.UNM in the window steitus word; otherwise, this routine clears 

WS.UNM. 

The routine next loads the user mode Active Page Register set with the cor- 
rect values to map this window to this region. 

Finally, the routine updates the window control block values W.BRCB, 
W.BHVR, W.BOFF, W.BNPD, and W.BLPD. 

4.7.4 Getting the Mapping Status: .GiVICX 

Issue the .GMCX programmed request to obtain the current mapping 
status of a particular virtual address window. 

First, the .GMCX monitor routine looks at the corresponding window con- 
trol block for this window. If you specify a window whose identification is 0, 
you obtain the status of the static window for a virtual job. There is no win- 
dow with the identification of 0' in a privileged job. If there is any problem 
with the window, the request returns with error code 3. 

The routine sets W.NAPR in the window definition block to be equal to the 
top three bits of W.BLVR in the window control block. This sets up the 
starting Active Page Register set number. 

Next, the routine puts values into W.NBAS, W.NSIZ, and W.NRID in the 
window definition block. 

If the window is not currently mapped, the routine clears W.NOFF, 
W.NLEN, and W.NSTS in the window definition block. If the window is 
mapped, the routine puts the offset into the region in W.NOFF, puts the 
length of the window in W.NLEN, and sets the bit WS.MAP in the window 
status word. 

4.7.5 Unmapping a Window: .UNIVIAP 

Issue the .UNMAP programmed request to explicitly unmap a window 
from a region. 

First, the monitor's .UNMAP routine finds the appropriate window control 
block. It checks W.NID in the window definition block. If the value is 0, or 
if it is invalid for any reason, the request returns with error code 3. If the 
window is not currrently mapped, the request returns with error code 5. 
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To unmap the window, the routine modifies the appropriate data struc- 
tures. It clears W.BRCB in the window control block, and decrements 
R.BNWD in the region control block. 

If the job is virtual, the routine clears the Page Descriptor Registers that 
correspond to this window so that your program can no longer reference the 
virtual addresses in this window. 

If the job is privileged, the monitor copies the kernel Page Descriptor 
Register values into the user Page Descriptor Registers so that the map- 
ping defaults to that of kernel mode. 

Finally, the routine sets WS.UNM in the window status word. 

4.7.6 Eliminating a Region: .ELRG 

Issue the .ELRG programmed request to eliminate a physical address 
region. 

First, the monitor's .ELRG routine checks to see if the region identification 
you specified is 0. In a virtual job, a region identification of indicates the 
static region, which you cannot eliminate. In a privileged job, there is no 
region whose identification is 0. In either case, the request returns with er- 
ror code 2. 

Next, the routine looks for the corresponding region control block for this 
region. If the region identification is invalid for any reason, the request 
returns with error code 2. 

Then, the routine clears RS.CRR and RS.UNM in the region status word. If 
there are any windows mapped to this region, the routine unmaps them and 
sets RS.UNM. 

The routine deallocates the region by returning its physical address space 
to the monitor's list of free memory. 

Finally, the routine clears the region control block. 

4.7.7 Eliminating a Window: .ELAW 

Issue this programmed request to eliminate a virtual address window. 

As with the .ELRG request, the .ELAW routine first finds the 
corresponding window control block for this window. It checks W.NID in 
the window definition block. If the window identification is 0, or is not valid 
for any reason, the request returns with error code 3. 

The routine next clears WS.CRW and WS.UNM in the window status word. 

If the window was mapped, the routine unmaps it and sets WS.UNM. The 
routine eliminates the window by clearing W.BSIZ in the window control 
block. Finally, the routine sets WS.ELW in the window status word. 
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4.7.8 Summary of Extended Memory Programmed Request Error 
Codes 

Table 4-14 summarizes the error codes that the extended memory program- 
med requests can put into byte 52. Table 4-15 shows which error codes each 
programmed request can use. 



Tabl<5 4-14: Extended Memory Programmed Request Error Codes and 
Meanings 



Byte 52 
Code 



Meaning 



There is a problem with the window ID. The window is too large, the 
value of W.NAPR is greater than 7, or you specified it incorrectly. 

1 You tried to create more than seven windows in your program. 
Remember that the static window is always defined for a virtual job, and 
one window is always reserved by the monitor in a privileged job. You 
can either unmap another window and then try to create a window, or 
you can redefine your virtual address space into fewer windows. 

2 The region identification was invalid for some reason. 

3 The window identification was invalid for some reason. 

4 The combination of the offset into the region and the size of the window 
to map to the region is invalid. 

5 The window you specified was not currently mapped. 

6 You tried to create more than three regions in your program. Remember 
that the static region is always defined for a virtual job, and one region is 
always reserved by the monitor in a privileged job. You can eliminate 
another region and then try to create a new one, or you can redefine your 
physical address space into fewer regions. Note that extended memory 
overlays and XM .SJETTOP account for one region each. 

7 There is not enoughi memory available to create a region as large as the 
one you requested. The routine returns the size of the largest available 
region in RO, but does not create it. 

10 You specified an im^alid size for a region. A value of or a value greater 

than 96K words is invalid. 



Table 4-15: Summary of Error Codes 

Programmed Request 



Error Code 
01234567 10 



.CRRG 

.CRAW 

.MAP 



XXX 



X X 



XXX 
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Table 4-15: Summary of Error Codes (Cont.) 

Error Code 
Programmed Request 0123456789 10 

.GMCX X 

.UNMAP X X 

.ELRG X 

.ELAW X 



4.8 Restrictions and Design impiications 

The manner in which RT-ll's support for extended memory is im- 
plemented imposes some restrictions on the ways you can use the system. 
The following sections outline the implications of the design of the extended 
memory system. 

4.8.1 PARI Restriction 

The RT-11 monitor sometimes "borrows" kernel Page Address Register 1 
for its own use. For example, it uses PARI to map to the EMT area blocks 
when it processes a programmed request. 

Because the monitor alters kernel PARI, references to virtual addresses in 
the range 20000 through 37777 do not always access the corresponding 
physical addresses. To avoid problems due to the occasional remapping of 
the virtual addresses controlled by kernel PARI, observe the following pro- 
gramming restrictions. 

1, Any channel areas you allocate with the .CDFN program request must 
be entirely within the low 28K words of memory. In addition, they 
must not be located within the addresses 20000 through 37777, 

2, Any queue elements you allocate with the .QSET programmed request 
must be entirely within the low 28K words of memory. In addition, 
they must not be located within the addresses 20000 through 37777. 
Remember to allow 10 decimal words per queue element, 

3, Interrupt service routines must be located entirely within the low 28K 
words of memory. In addition, they must neither reside in nor 
reference addresses in the range 20000 through 37777. Section 6.7 
describes the factors you must take into consideration if your program 
includes an in-line interrupt service routine. Be sure to execute your 
program as a privileged job if it contains an interrupt service routine, 
so that it can access the monitor and the device I/O page. Section 7,9 
lists the implications of the XM design restrictions on device handlers 
and I/O. 
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This aspect of RT-ll's design is important for you to understand if you 
have a program with its own in-line interrupt service routine, if you put a 
data buffer for I/O in extended memory, or if you write a device handler for 
an XM system. 



4.8.2 Programmed RequesHs 

Some of the RT-11 programmed requests have special restrictions when 
you use them in an extended memory system. These requests and their 
restrictions are as follows: 



Programmed Request 
.CDFN 

.QSET 
.CNTXSW 



Restriction 

The channel area you specify in this request must be 
entirely within the low 28K words of memory. 

The queue element space you specify must be entirely 
within the low 28K words of memory. In addition, you 
must allow 10 decimal words for each queue element. 

Virtual jobs cannot use this request, since they have no 
nesed for it in an extended memory system. 



4.8.3 PAR2 Restriction 

The MQ message handler resides within the physical memory mapped by 
Page Address Register 2. If you use the MQ handler to send and receive 
messages, be sure to read Section 3.5.7. When you use the MQ handler, all 
the PARI restrictions apply as well to the virtual addresses controlled by 
PAR2: the addresses in the range 40000 through 57777. 

4.8.4 Synchronous Systemi Traps 

A synchronous system trap iis a software interrupt that takes place syn- 
chronously with your program's execution. For example, a TRAP instruc- 
tion that a program issues is a synchronous system trap. A program that 
issues an illegal instruction causes a trap to 10 to occur, which is also a syn- 
chronous system trap. When a trap occurs, the PDP-11 computer pushes 
the current PS and PC onto the stack and loads the new PS and PC from the 
contents of the trap vector. Table 4-16 lists the sychronous system traps 
and their corresponding vectors. 

Table 4-16: Synchronous System Traps and Their Vectors 

Vector Synchronous System Trap 

4 Trap to 4, caused by a reference to an odd address, or by a bus time-out. 

10 Trap to 10, caused by an attempt to execute a reserved instruction. 

14 Breakpoint trap, visually issued by a debugging utility program such as 

ODT. 
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Table 4-16: Synchronous System Traps and Their Vectors (Cont.) 
Vector Synchronous System Trap 



20 I/O trap. 

34 TRAP instruction, issued by a program to change the flow of execution. 

114 Memory parity trap, caused by a memory parity error. 

244 FPU trap, caused by a floating point unit exception or error. 

250 Memory management trap, caused by a program's attempt to reference 

a virtual address that is not mapped to a physical address. 

In an XM system, sychronous system traps, like device interrupts, take the 
new PS and PC from the appropriate vector in kernel space. For example, 
when a program issues a BPT instruction, the new PS and PC are taken 
from physical locations 14 and 16. As you remember, a privileged job is in- 
itially mapped to the kernel vector area, so virtual address 14 in the pro- 
gram maps to physical location 14. A virtual job, on the other hand, is 
prevented from accessing the kernel vector area. Initially, the virtual job's 
virtual vector area maps to physical addresses starting at location 500, not 
0. For a virtual job then, the virtual vector 14 is not in physical location 14. 

For each sychronous system trap, RT-11 provides a mechanism to field the 
trap and provide values for the new PS and PC from the virtual vector. The 
following sections describe the effect of the XM environment on specific 
sychronous system traps. 

4.8.4.1 TRAP, BPT, and lOT Instructions — When a program in an XM system 
issues a TRAP, BPT, or lOT instruction, execution switches to the proc- 
essor's kernel mode. The hardware picks up the contents of the appropriate 
vector (see Table 4-16) from kernel space. However, rather than dis- 
patching immediately to the trap handling routine specified in the kernel 
vector, the monitor replaces the new PS and PC with values that cause ex- 
ecution to continue within a monitor routine. The purpose of the monitor 
routine is to pick up the contents of the corresponding virtual vector in user 
space, and then transfer control to the routine specified by the virtual PC. 
The kernel and user vectors for a privileged job are identical. A virtual job 
cannot access the kernel vectors; you can, however, put values into the vir- 
tual vectors so that the monitor will pick them up when a trap occurs. In 
summary, the net effect of the monitor's trap handling routine is that con- 
trol is transferred to a job's specific trap routine through the contents of 
the job's virtual vector. 

If the virtual vector contains an even, nonzero value, the monitor does not 
clear the vector after the first trap. This permits recursion with no effort on 
the part of the program. 

4.8.4.2 Traps to 4 and 10, and FPU Traps — For traps to 4 and 10, and floating 
point unit exception traps, the monitor provides a mechanism that protects 
the vectors while still permitting you to use your own trap handling 
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routines. The .TRPSET and .SFPA programmed requests permit your pro- 
gram to set up the addresses of trap handling routines without modifying 
either the kernel or the user virtual vector area. These two programmed re- 
quests function in XM systems the way they do in FB systems. Thus, you 
specify the address of your trap handling routine when you issue the pro- 
grammed request and the monitor puts this information in the job's impure 
area, The monitor clears out the routine address in the impure area, so your 
trap handling routine shoxild reset this area by issuing either .TRPSET or 
.SFPA as its last instruction before returning to the main program. 

4.8.4.3 Memory Management Faults — A memory management fault occurs 
when a program references a virtual address that is not mapped to a 
physical address. If a memory management fault occurs while execution is 
in system state, the entire system halts. If a memory management fault oc- 
curs while execution is in user state, the monitor fields the trap through the 
kernel vector and provides a new PS and PC from the user virtual vector 
area, Once the monitor picks up the contents of a job's virtual vector, it 
clears the vector. If a second fault occurs and the virtual vector is 0, the 
monitor prints its 9M0N-F-MMU fault message and aborts the job. 

To permit recursion, your program's trap handUng routine must reset the 
contents of the memory management fault vector (at locations 250 and 252) 
in the job's virtual vector area. If RT-11 permitted automatic recursion, 
your program could loop indefinitely on a memory management fault until 
you halted the processor. 

4.8.4.4 Memory Parity Errors — A hardware device that is an optional part of 
your PDP-11 computer syst«sm performs memory parity checking. You 
enable RT-11 support of this hardware option by selecting the memory 
parity special feature at system generation time. If you have memory pari- 
ty hardware but do not generate a system with the memory parity checking 
special feature, a memory parity error causes a system halt. 

For systems that support memory parity checking, the sychronous system 
trap procedure is similar to the procedure for memory management faults. 
Thus, the monitor fields the trap through the kernel vector at locations 114 
and 116. It then picks up the c;ontents of your program's virtual addresses 
114 and 116, clears them, and passes control to your trap handling routine 
based on the new PS and PC. 

If a second memory parity error occurs and the virtual vector is 0, the 
message ?MON-F-Mem err prints and the job aborts. To enable recursion, 
your program's trap handling routine must reset the contents of the 
memory parity fault vector at virtual addresses 114 and 116. 

4.9 Debugging an XM Application 

Use VDT, the Virtual Debugging Technique, to debug virtual and privileg- 
ed jobs in an XM system. VDT eilso handles correctly jobs in FB and SJ 
systems, as well as jobs in multi-terminal systems. 
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Use VDT.OBJ the same way you use ODT.OBJ; link it with the program 
you need to debug. The transfer address for VDT is O.ODT. The syntax for 
VDT commands is the same as the syntax for ODT. See the RT-11 System 
User^s Guide for instructions on using ODT. 

VDT.OBJ is created from a conditional assembly of ODT.MAC, with the 
conditional $VIRT equal to 1. VDT.OBJ is provided on the distribution kit; 
you need not assemble it yourself. VDT does not contain the interrupt ser- 
vice or priority routines that ODT does. Unlike ODT, which runs at priority 
7 and performs its own terminal I/O, VDT runs at the same priority as your 
program, and uses .TTYIN and .TTYOUT programmed requests to per- 
form terminal I/O. 

Because VDT uses .TTYIN and .TTYOUT requests, you can run it from a 
job's console terminal; it is not limited to the hardware console interface. 
Since VDT alters the contents of the Job Status Word, it must save the 
original contents elsewhere. You can use the $J/ command to obtain the 
original contents of the JSW; you can also modify it there. 

VDT runs in user, not in kernel mode. When you debug a virtual job with 
VDT, you are limited to accessing the job's area only. You cannot access 
the protected system areas such as the monitor, the vectors, and the I/O 
page. When you debug a privileged job with VDT, you have access to the 
same memory the job does. 

4.10 Extended Memory Example Program 

Figure 4-45 provides an example program that uses extended memory pro- 
grammed requests. 

Figure 4-45: Extended Memory Example Program 

XMCOPY MACRO U04.00 4-0CT-79 16:53!02 PAGE 1 

1 .TITLE XMCOPY 

2 ; + 

3 } THIS IS AN EXAMPLE IN THE USE OF THE RT-11 EXTENDED 

4 ; MEMORY REQUESTS. THE PROGRAM COPIES FILES AND THEN 

5 f VERIFIES THE RESULTS. IT USES EXTENDED MEMORY TO 

6 F IMPLEMENT 4K TRANSFER BUFFERS, THIS PROGRAM USES MOST 

7 ( OF THE EXTENDED MEMORY PROGRAMMED REQUESTSi AND 

8 ; DEMONSTRATES OTHER PROGRAMMING TECHNIQUES, 

9 ;- 

10 .NLIST BEX 

11 . .MCALL .UNMAP) .ELRG>.ELAU> .CRRG) .CRAUr .MAP 

12 .MCALL .PRINT. .EXIT, .CLOSE, .CSlGENf .READUf.URITW 

13 .MCALL .RDBBK, .WDBBK,. TTYOUT, .WDBDF,.RDBDF 

14 000044 JSU = 44 J JSW LOCATION 

15 002000 J.VIRT = 2000 JVIRTUAL JOB BIT IN JSW 

16 000052 ERRBYT = 52 JERROR BYTE LOCATION 

17 000002 APR = 2 ;PAR/PDR FOR 1ST WINDOW 

18 000004 APRl =4 ; ' " 2ND 

19 000736' BUF = UDB+W.NBAS JMIRTUAL ADDR OF 1ST 

20 i BUFFER 

21 000762' BUFl = WDBl+W.NBAS ^VIRTUAL ADDR OF 2ND 



"?? 



BUFFER 
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Figure 4-45: Extend Memory Example Program (Cont.) 



23 

24 

25 

2(4 

27 

28 

29 

30 000000 

31 

32 

33 000044 

34 000000 
35 

36 000000 

37 

38 000000 

39 

40 

41 000000 
000000 
000004 
000010 
000012 

42 

43 000014 

44 000016 

45 000022 
000022 
000026 
000032 
000040 

46 000042 

47 000044 
48 

49 000050 
50 

51 000056 

52 000062 
000062 
000066 
000072 
000100 

53 000102 
34 000104 

55 000110 

56 000114 
000114 
000120 
000124 
000132 

57 000134 

58 000136 

59 000142 
60 

61 
42 



000144 
000150 
63 000154 
000154 
000160 
00 0164 
000170 
000176 
000202 
000206 



65 000210 

66 000212 

67 000216 

68 000220 
69 

70 000224 



010000 
000020 
000742' 

000766' 



000044 
002000 



COREIIZ 
PA6£!IZ 
URN I II 



4096, 

CORSIZ/256. 

WDB+W.NRID 



START! 



012746 
012746 
005046 
104344 

103771 
105267 

012700 
012710 
012760 
104375 
103002 
000167 

016767 lot: 

105267 

012700 
012710 
012760 
104375 
103002 
000167 
105267 



012700 
012710 
012760 
104375 
103002 
000167 
005001 

012702 
105267 

012700 
012710 
010160 
016760 
010260 
005060 
104375 

103005 
105737 
001431 
000167 



J0»! 



30t! 



READ! 



URNIDl = WDBl+U.NRIti 



.ASECT 



010002 WRITE! 



.= JSU 

.WORD 

.PSECT 

. WHBDF 

, RD6DF 



•CSIGEN 

HOV 

hOV 

CLR 

EMT 

BCS 

INCB 

.CRRG 

Moy 

MOV 

Moy 

EMT 
BCC 
JMP 

Moy 

INCB 

.CRAW 

MOV 

MOV 

MOV 

EMT 

BCC 

JMP 

INCB 

• MAP 

MOV 

MOV 

MOV 

EMT 

BCC 

JMP 

CLR 

MOV 

INCB 

.REAOW 

MOV 

MOV 

MOV 

MOV 

MOV 

CLR 

EMT 

BCC 
TSTB 
BEO 
JMP 

MOV 



J.VIRT 



5SIZE OF BUFFER IN WORDS 
SPACE SIZE IN BLOCKS 
iREGION ID ADDR OF 1ST 
r REGION 

^REGION ID ADDR OF 2ND 
) REGION 

JASSEMBLE IN THE VIRTUAL 
i JOB BIT 

(MAKE THIS A VIRTUAL JOB 
(START CODE NOW 

(CREATE WINDOW DEFINITION 

! BLOCK SYMBOLS 

(CREATE REGION DEFINITION 

( BLOCK SYMBOLS 



*ENDCRE,*DEFLTr*0 
*ENDCREf-<6. ) 
*DEFLTr-(6. ) 
- ( 6 , ) 
"0344 



(GET FILESPECS, 



START 

ERRNO 

#CAREAt*RDB 

♦CAREArXO 

»30.*"D400+0» (0) 

♦RDBf 2. (0) 

"0375 

10$ 

ERROR 

RDBjWRNID 



ERRNO 

tCAREArtWDB 

♦CAREA.XO 

♦30.*"0400+2. t (0) 

♦WDB,2. (0) 

"0375 

20* 

ERROR 

ERRNO 

tCAREArtUDB 

♦CAREAiXO 

*30.*"0400+4. » (0) 

♦WDBj2. (0) 

"0375 

30» 

ERROR 

Rl 



; HANDLERSi OPEN FILES 
(BRANCH IF ERROR 
(ERR = IX 
(CREATE A REGION 



(BRANCH IF SUCCESSFUL 

(REPORT ERROR 

( (JMP DUE TO RANGE! J 

(MOVE REGION ID TO WINDOW 

( DEFINITION BLOCK 

(ERR = 2X 

(CREATE WINDOW. . . 



(BRANCH IF NO ERROR 
(REPORT ERROR. . . 
(ERR = 3X 
(EXPLICITLY MAP 



WINDOW. , 



♦C0RS1Z.R2 

ERRNO 

♦RAREAf *3rBUFrR2FRl 

♦RAREA.ZO 

♦3+ <8.*"0400>, (0) 

R 1 > 2 . ( > 

BUF,4. (0) 

R2»6. (0) 

8.(0) 

"0375 



(BRANCH IF NO ERROR 

(REPORT ERROR 

(Rl = RTll BLOCK # 

( FOR I/O 

(R2 = * OF WORDS TO READ 

(ERR = 4X 

TRY TO READ 4K-W0RTH 



WRITE 
etERRBYT 
PASS2 
ERROR 

R0rR2 



( OF BLOCKS 

(BRANCH IF NO ERROR 

(EOF? 

(BRANCH IF YES 

(MUST BE HARD ERRORr 

( REPORT IT 

(R2 = SIZE OF BUFFER 
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Figure 4-45: Extend Memory Example Program (Cont.) 



71 

72 000226 
000226 
000232 
000236 
000242 
000250 
000254 
000260 

73 000262 
:'4 000264 

75 000270 

76 000274 

77 000300 
78 

79 000302 

80 000306 
000306 
000312 
000316 
000324 

81 000326 

82 000330 

83 000334 
84 

85 
36 
87 
88 

89 000342 

90 000346 
000346 
000352 
000356 
000364 

91 

92 000366 

93 000370 

94 000374 

95 000400 

96 000402 

97 000406 
000406 
000412 
000416 
000422 
000430 
000434 
000440 

98 

99 000442 

100 000444 

101 000450 

102 000452 

103 000456 

104 000460 
000460 
000464 
000470 
000474 
000502 
000506 
000512 

105 

106 000514 

107 000516 

108 000522 

109 000526 

110 000532 

111 000536 
112 

113 000540 

114 000542 



012700 
012710 
010160 
016760 
010260 
005060 
104375 
103004 
105267 
000167 
062701 
000725 



AIiniT! 



105267 fASS2! 

012700 
012710 
012760 
104375 
103002 
000167 
016767 35$: 



.URITW 


♦RAREAi*OfBUF 


MOM 


♦RAREAfXO 


MOV 


*0+<9.*"0400> 


MOM 


Rli2. (0) 


MOV 


EUFi4. (0) 


MOV 


R2 > 6 . < ) 


CLR 


8.(0) 


EMT 


"0375 


BCC 


ADDIT 


INCB 


ERRNO 


JMP 


ERROR 


Arm 


♦PAOSIZrRl 


BR 


READ 


INCB 


ERRNO 


• CRRG 


*CAREA,*RDEil 


MOV 


♦CAREA.XO 


HOV 


*30,*"0400+0f 


MOV 


*RDB1»2.(0> 


EMT 


"0375 


BCC 


35$ 


JMP 


ERROR 


MOV 


RDBlrWRNIDl 



; JUST READ 
,R2fRl (WRITE OUT THE BUFFER 

( (0) 



(BRANCH IF NO ERROR 
!ERR = 5X 
(REPORT ERROR 
(ADJUST BLOCK * 
(THEN GO GET ANOTHER 
( BUFFER 
(ERR = 6X 
(CREATE A REGION 



(0) 



(BRANCH IF NO ERROR 
(REPORT ERROR 
(GET REGION ID TO WINDOW 
( DEFINITION BLOCK 



(* EXAMPLE USING THE .CRAW REQUEST DOING * 
(* IMPLIED .MAP REQUEST. * 



105267 

012700 
012710 
012760 
104375 

103002 
000167 
105267 
005001 
012702 

012700 
012710 
010160 
016760 
010260 
005060 
104375 

103005 
105737 
001441 
000167 
010002 

012700 
012710 
010160 
016760 
010260 
005060 
104375 

103004 
105267 
000167 
016704 
016703 
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.CRAW 
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. JMP 

verify:: incb 
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CLR 

EMT 
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TSTB 

BEQ 

JMP 
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.READW 

MOV 

MOV 

MOV 

MOV 

MOV 

CLR 

EMT 



40$; 



50$: 

70$: 
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JMP 
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MOV 

CMP 
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tCAREArtWDBl 

tCAREAfXO 

*30.*"0400+2. 

*UDB1>2. (0) 
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VERIFY 

ERROR 

ERRNO 

Rl 

*C0RSIZrR2 
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BUF1.4. (0) 
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*0+<8.*"0400>» 
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8. (0) 
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50$ 

ERRNO 

ERROR 

BUFrR4 

BUF1.R3 

(R4)+> (R3)+ 

ERRDAT 
R2 



(ERR = 7X 

(CREATE WINDOW USING 



' (0) 



( IMPLIED .MAP 
(BRANCH IF NO ERROR 
(REPORT ERROR 
(ERR = 8X 

(Rl = RTll BLOCK » AGAIN 
(R2 = 4K BUFFER SIZE 
,R2,R1 (TRY TO GET 4K-W0RTH 

(0) 



( OF INPUT FILE 
(BRANCH IF NO ERROR 
(EOF? 

(BRANCH IF YES 
(REPORT HARD ERROR 
(R2 = SIZE OF BUFFER READ 
R2fRl (TRY TO GET SAME SIZE 

<0) 



( FROM OUTPUT FILE 

(BRANCH IF NO ERROR 

(ERR = 9X 

(REPORT ERROR 

(GET OUTPUT BUFFER ADDRESS 

(GET INPUT BUFFER ADDRESS 

(VERIFY THAT DATA IS THE 

( SAME 

(IT'S NOT> REPORT ERROR 

(ARE WE FINISHED? 
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Figure 4^-45: Extend Memory Example Program (Cent.) 
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*0 
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.UNMAP 
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012760 




MOV 
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104375 




EMT 
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.ELRG 
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MOV 
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MOV 
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.PRINT 
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EMT 


"0351 
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000722 




BR 
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EMT 
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BR 
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.WORD 
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145 


000752 
000752 


000000 
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000200 




.WORD 
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000760 
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Extended Memory Feature 4-73 



Figure 4-45: Extend Memory Example Program (Cont.) 
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000766R 


APRl = 
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BUFl = 
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RDE 


000726R 


MS.MAP= 
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RDBl 
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U.NAPR= 
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DEFLT 
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ENDCRE= 
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ENDIT 
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ENDPRG 
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000004 
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ERRNO 
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VERIFY 
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. . .U2 = 
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virtual memory used: 10496 words ( 41 pages) 
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>xmcopy/l:mee/l;ttm=xmcopy 



4-74 Extended Memory Feature 



Chapter 5 
Multi-Terminal Feature 



In describing the multi-terminal feature of RT-11 this chapter provides 
background information on the hardware and describes the data structures 
of a multi-terminal system. It also describes the interrupt service and poll- 
ing routines, the programmed requests available to appUcation programs, 
and typical situations in which you can use two terminals without making 
use of the multi-terminal special feature. Finally, restrictions are hsted and 
a sample program is provided. 

5.1 Components of a Multi-Terminal System 

RT-11 implements support foi- multiple terminals as a special feature that 
you select at system generation time and that is available to SJ, FB, and 
XM monitors. Essentially, the multi-terminal feature permits an 
appHcation program to control one or more terminals. It does not change 
RT-ll's basic characteristic of being a single-user operating system. 
Specifically, multi-terminal supiport does not permit more than one terminal 
at a time to be the command terminal, the terminal at which you 
communicate with RT-11 through the keyboard monitor commands. 

Supp>ort for multiple termintils is implemented through the following 
components: 

• MTTEMT.MAC, which jprocesses the multi-terminal programmed 
requests. 

• MTTINT.MAC, which contains the multi-terminal interrupt service 
and polling routines. 

• SYSTBL.MAC, which defines the multi-terminal terminal control 
blocks. 

MTTEMT, MTTINT, and SYSTBL assemble and Unk together as part of 
the Resident Monitor for a multi-terminal system. 

There are also some important data structures in multi-terminal systems: 

• Terminal control blocks, called TCBs (one per terminal), which contain 
information about the terminal and the job. The TCBs also contain the 
input and output ring buffers for the terminal. 

• Logical unit numbers, calksd LUNs, through which RT-1 1 refers to the 
terminals that are peirt of your system. 
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• Asynchronous terminal status words, called AST words (one per 
LUN), in which RT-11 maintains event flags to reflect the current 
status of each terminal. This word is a special feature you can select at 
system generation time. 

5.2 Hardware Background Information 

This section provides some background information that is useful if you are 
unfamiliar with the communication hardware RT-11 supports. 

RT-11 can support both the DL series (including DLll and DLVll, or com- 
patible equivalent, such as the PDT-11 terminal and modem ports) and the 
DZ series (including DZll and DZVll) of serial interfaces. An interface is 
similar to a device controller; it stands between the computer and a serial 
line. The other end of the line can be connected to a terminal, a communica- 
tion device, a peripheral device, or another computer. 

The DL interface connects the computer system to a single serial line. Each 
DL interface has its own Control and Status Register (CSR) address and 
vector address. You can have as many as eight DL interfaces on your com- 
puter system, including the hardware console interface. Since each DL in- 
terface is a separate controller, there is no real physical unit number; is 
assigned for consistency. Note that even though the DLVll-J module con- 
tains four serial lines, they appear to the software as four separate and 
distinct DL interfaces. 

Each RT-11 system must have a hardware console interface so that the 
hardware can use it at bootstrap time to locate the console terminal. The 
hardware bootstrap on many systems requires that a terminal be connected 
at the standard console addresses for diagnostic purposes and for operator 
communication at bootstrap time. Your hardware console interface must be 
a local DL. Its interrupt vectors are located at 60 and 64 in low memory, 
and its LUN is always 0. 

A DZ interface is called a multiplexer; it connects several serial lines 
through a single pair of CSR and vector addresses. The DZll interface con- 
nects the computer system to eight lines that have physical unit numbers 
from through 7. The DZVll is similar to the DZll, but it connects the 
system to only four lines that have physical unit numbers from through 3. 
You can have two DZll or four DZVll interfaces, for a total of 16 addi- 
tional lines. 

Figure 5-1 illustrates DL and DZ interfaces and their physical and logical 
unit numbers. 

At system generation time, you specify through the SYSGEN dialogue how 
many DL and DZ interfaces your target system has. You also indicate how 
many of their physical units are actually connected to terminals on the 
system. Of those terminals, you must indicate which are local and which are 
remote lines. Unlike physical unit numbers, which are numbered starting at 
for each interface, the logical unit numbers that RT-11 uses are unique. 
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Figure 5-1: Interfaces and Physical and Logical Unit Numbers 



RT-11 SYSTEM 



DL 
CONSOLE 



DL 



DZ 
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LUN: 



001234567 
123456789 



They begin at and continue until all terminals have been accounted for. 
SYSGEN assigns the physical unit numbers of the interfaces to its soft- 
ware logical unit numbers in the following order: 

1. Local DL lines (the hardv/^are console interface is always LUN 0) 

2. Remote DL lines 

3. Local DZ Unes 

4. Remote DZ Unes 

The order in which SYSGEN assigns physical lines to logical unit numbers 
is also the order in which it generates the terminal control blocks. It 
generates one TCB for each Urie you specify in the SYSGEN dialogue. The 
TCBs are arranged in RMON in the order in which you specify the Unes to 
SYSGEN. There are no TCBs for any unused interface physical Unes. 

PDT-11 systems with cluster controUers, and PDP-11/03 and 11/23 
systems with a DLVll-J interface (such as the MINC-11) have three addi- 
tional DL interfaces at the standard addresses. The PDT-11 ports are label- 
ed with terminal numbers that are the same as the corresponding RT-11 
logical unit numbers. MINC-11 systems have SLU (serial Une unit) port 
numbers; the RT-11 logical unit number corresponding to a port is the SLU 
number plus 1. 

When you bootstrap a multi-terminal system, RT-11 checks for the 
presence of each interface for which a TCB exists by attempting to access 
its CSR, as specified in the SYSGEN dialogue. If the interface does not ex- 
ist, the logical unit number associated with that interface is marked as 
nonexistent, and any attempt t;o attach such a LUN results in an error. The 
space occupied by the TCB of a nonexistent LUN is not recoverable. You 
can use the SHOW TERMINALS monitor command to verify that the in- 
formation you supplied during system generation was correct. 
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Note that RT-11 does not attempt to determine whether or not a terminal 
or modem is actually connected to an interface line; it assumes the connec- 
tion is present. For an unconnected line, no input characters can be 
generated; output directed to the line is sent out and lost. 

5.3 What Is the Console Terminal? 

A potentially confusing aspect of RT-ll's multi-terminal support is its 
ability to change the console terminal. This section defines precisely what is 
meant by the terms hardware console interface, boot-time console, 
background console, and private console. You will avoid confusion if you 
famiUarize yourself with these terms and use them consistently. 

The hardware console interface, as Section 5.2 describes, is the terminal in- 
terface located at vectors 60 and 64, whose control and status registers 
begin at 177560 in the I/O page. This is the serial Une interface the hardware 
bootstrap uses at bootstrap time. (Generally, you must have a terminal con- 
nected to the hardware console interface in order to bootstrap the system.) 
This is almost always the terminal on which RT-11 prints its startup 
message. Remember that the hardware console interface is always LUN 0. 

The boot-time console is the terminal on which RT-11 prints its startup 
message. This is almost always the same as the terminal connected to the 
hardware console interface. In a system without the multi-terminal feature, 
the CSR for this terminal, 177560, is contained in TTKS. (TTKS is located 
at fixed offset 304 from the start of the Resident Monitor.) In a multi- 
terminal system, the CSR is located at offset T.CSR in the first TCB in the 
Resident Monitor. 

The background console, also called the command console, is originally the 
same as the boot-time console. (It remains the same until you use the SET 
TT: CONSOL command, described below, to move the background console.) 
It is the terminal on which you type commands to the Keyboard Monitor, 
and through which you communicate with the background job. If you run a 
foreground job or system jobs, they can share the background console. In 
this case, you must use CTRL/B to communicate with the background job, 
CTRL/F for the foreground job, and CTRL/X for the system jobs. For ex- 
ample, to abort a job from a shared console, you must type the appropriate 
CTRL sequence, followed by two CTRL/C characters. (See Chapter 3 for 
more information on control sequences.) 

The programmed requests .TTYIN, .TTYOUT, .CSIGEN, .CSISPC, 
.GTLIN, and .PRINT interact with the background console for the 
background job, and also for any foreground or system jobs that happen to 
be sharing this terminal. 

NOTE 

RT-11 ignores any unit number you specify with device 
TT. Therefore, references to TT:, TTO:, TTl:, and so on, are 
all equivalent, and default to the background console. 
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In a multi-terminal system you can move the background console to 
another terminal by issuing thie SET TT: CONSOL monitor command. By 
specifying another logical unit number in the SET command, you can move 
the background console to any other local terminal in the system, except to 
a private console. 

A private console is a local terminal used by a single foreground or system 
job. You give a job its own private console when you start the job by using 
the FRUN/TERMINAL:n or SRUN/TERMINAL:n commands. No other 
job can share a private console with the original job. A job's private console 
is the terminal with which its .TTYIN, .TTYOUT, .CSIGEN, .CSISPC, 
.GTLIN, and .PRINT programmed requests interact. In addition, any 
.READ or .WRITE requests to TT that this job makes access the private 
console. When a job has its own private console, you can no longer com- 
municate with the job through the background console. Thus, you can no 
longer use CTRL/F at the background console, for example, to interact with 
a foreground job that has its OMm private console; instead, you must type on 
the private console. To abort this foreground job, you must type two 
CTRL/Cs on its private console. You cannot issue keyboard monitor com- 
mands from a private console. 

You cannot change a private console to a different terminal by using the 
SET TT: CONSOL command; that command is vaUd only for the 
background console. This is because the Keyboard Monitor runs as a 
background job, and it can run only on the background console. The 
background console is private if there are no jobs sharing it. 

A shared console refers to the background console unless the following con- 
ditions apply: 

1. In an FB or XM system without the system job feature, the 
foreground job is running with a private console. 

2. In an FB or XM system with the system job feature, all six system 
jobs and the foreground job are running, and each has a private con- 
sole. 

Remember that a private console can never be shared. 

A coinsole simply refers to a terminal being used as the background shared 
console, or as a foreground or system job private console. 



5.4 Using Two or More Terminals 

There £ire several situations in which you may need to use more than one 
terminal, but you do not need any of the special features available through 
the multi-terminal programmed requests. The following sections describe 
some of those situations and show how to arrange the terminals, often 
without generating support for the multi-terminal feature. 
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5.4.1 A Video Console Terminal and a Hard Copy Printing Terminal 

A typical situation that arises in RT-11 applications is the case in which it 
is desirable to use a video terminal as the background console terminal and 
a hard copy terminal as a line printer. The next two sections describe the 
procedures to use, depending on whether the video terminal or the hard 
copy terminal is the boot-time console. 

5.4.1.1 The Video Terminal is the Boot-Time Consoie — If your video terminal 
is the boot-time console, it is simple to use a hard copy printing terminal as 
a line printer. (Note that the hard copy terminal must be on a DL interface 
to use this procedure.) You set up the vectors and CSR addresses for the 
hard copy terminal in the LS device handler file (by using the SET LS: com- 
mands described in the RT-11 System User's Guide) and install LS. You 
can then simply assign LP to LS and proceed to use the hard copy terminal 
as a line printer. 

This is the simplest of multiple-terminal appHcations, since it does not in- 
volve system generation. This procedure is not effective, however, if the 
hard copy terminal is not on a local DL interface. 

Under many circumstances, it may be desirable to have the hard copy ter- 
minal become the console terminal. Use the procedure described in Section 

5.4.2 to do this. 

5.4.1.2 The Hard Copy Terminal is the Boot-Time Consoie — How you make the 
hard copy terminal the line printer when the hard copy terminal is the boot- 
time console depends on whether the video terminal is on a DL or DZ inter- 
face. If the video terminal is on a DL interface, there are four possible ap- 
proaches that permit you to use the hard copy terminal as a line printer. 

In Procedure 1 you can perform a system generation (without including the 
multi-terminal feature) to make the video terminal appear to be the boot- 
time console. Note that the hard copy terminal remains the hardware con- 
sole interface. That is, you must still type the name of the system device on 
the hard copy terminal in response to the $ prompt. However, RT-11 does 
print its boot message on the video terminal. Once the system is bootstrap- 
ped, you can use the LS handler to access the hardcopy terminal as a line 
printer. 

In Procedure 2 you can authorize a DIGITAL Field Service representative 
to change your system configuration so that the video terminal is the boot- 
time console, and the hard copy terminal is on a local DL interface. Then 
you can use the procedure outlined in Section 5.4.1.1. 

In Procedure 3 you can use a special program to switch the background con- 
sole to the video terminal. Except that the default boot- time console 
defaults to the hard copy terminal after each reboot, this is similar to pro- 
cedure 1, above. You can use the LS handler to access the hard copy ter- 
minal as a line printer. Section 5.4.2 shows the program you run to use Pro- 
cedure 3. 

Procedure 4 is similar to Procedure 3, except that you alter the monitor im- 
age on a mass storage device instead of in memory. This procedure is useful 
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only iin systems without the multi- terminal feature. Figure 5-2 shows the 
patch for Procedure 4, You must supply the correct value for the vector, 
CSR, protection offset, and protection code (see Section 3.6.1.2) for your ap- 
plication. 

Figure 5-2: Patch for Procedure 4 

! Permanent modification of monitor using CSR and Vector addresses 
! CSR = 175620-175626 /Vec = 310-316 



.RSiPP< RET> 
*monltr.SYS< RET> 
Base? ;S < RET> 
Search for? 60 < RET > 
Start? 5100 < RET> 

End? 5200 < RET> 

Found at nnnnnn 
Base? nnnnnn < RET> 
Offset? < RET> 



! monitr represents the file name 
I of the monitor fiie you are 
! changing 



Base 


Offset 


Old 


New? 


nnnnnn 


000000 


000060 


310<RET>! New vector 


nnnnnn 


000002 


xxxxxx 


'■Z<RET> 


Offset? 


6<RET> 






Base 


Offset 


Old 


New? 


nnnnnn 


000006 


000064 


314<RET>! New vector plus 4 


nnnnnn 


000010 


xxxxxx 


-Z<RET> 


Offset? 


-Z<RET> 






Base? 


$RiV10N<RET> 




! Find the value of $RMON on your 


Offset? 


304<RET> 




! link map. 


Base 


Offset 


Old 


New? 


$RIVION 


000304 


177560 


1 75620 <RET> I New CSR 


$RIVION 


000306 


177562 


1 75622 <RET> 1 New CSR 


$RIVION 


000310 


177564 


175624<RET> ! New CSR 


SRIVION 


000312 


177566 


175626<RET> ! New CSR 


$RMON 


000314 


177777 


-Z<RET> 


Offset? 


342<RET> 




! Offset for protection byte 


Base 


Offset 


Old 


New? 


$RMON 


000342 


000000 


17<RET> ! Enable protection 


$RMON 


000344 


000000 


-Y 


* 'G 









If the video terminal is on a DZ interface, you must perform a system 
generation for a multi-termimd system. Specify information about your 
system configuration to SYSGEN exactly as it exists. Once you bootstrap 
the new system, set the LS vector and CSR to those of the hard copy ter- 
minal (by using the SET LS: commands described in the RT-11 System 
User's Guide). Note that this action changes the handler file on a mass 
storage device, and that you cannot use the hard copy terminal in any 
multi-terminal application. You need to modify the vector and CSR only 
once. 
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Before you use the LS handler, issue the SET TT: CONSOL command to set 
the background console to the video terminal. Since this setting reverts to 
its original state after each bootstrap, put this SET command in your start- 
up indirect command file. 

NOTE 

You must never issue the SET TT: CONSOL = command 
or access LUN in any way; this is guaranteed to crash the 
system. 

5.4.2 Switching the Consofe Terminal 

Figure 5-3 lists a program called CONSOL that you can use to switch the 
console terminal to another terminal in a system without the multi-terminal 
special feature. Edit the source file to supply values for the CSR and vector 
for the new console; use the symbols CSRAD and VEC. To switch the con- 
sole back and forth between two terminals, maintain two copies of the pro- 
gram, one for each terminal. 

Figure 5-3: Program to Switch the Console Terminal 

.MAIN. MACRO U04.00 3-JAN-80 18:44:25 PAGE 1 



2 






! + 






3 






i 


PROGRAM 


TO CHANGE CONSOLE TO ONE 


4 
5 






f 

i- 


OTHER THAN POOT CONSOLE 


6 

7 
8 
9 








.MCALL 


.MTPS> .PRINT, .EXIT 




175620 




CSRAD 


= 175620 i*** NEW CONSOLE 


10 










(INPUT CSR *** 


11 




000310 




VEC 


= 310 ;*** NEW CONSOLE 


12 










JVECTOR *** 


13 




000372 




SYSCEN 


= 372 JOFFSET TO SYSGEN UORD 


14 




020000 




MTTVt 


= 20000 fMULTI-TERMINAL BIT IN 


15 










i SYSGEN UORD 


16 












17 




000017 




BHASK 


= 360/<<15.*<VEC-<20«<VEC/20>>>/8.>+l> 


18 




000342 




BITMAP 


= 326+<VEC/20> 


19 












20 


000000 


013700 
000054 


PR0C3: 


Moy 


e*54,R0 (RO => RMON 


21 


000004 


032760 
020000 
000372 




BIT 


*MTTY*,SYSGEN<RO) fMULTI-TERMINAL SYST 


22 


000012 


001044 




BNE 


2$ fYES - CAN'T USE THIS 


23 










(TECHNIQUE! 


24 


000014 






.MTPS 


7 iGO TO PRIORITY 7 ! N 




000014 


005046 


.IIF MB 


<7> 


CLR -(6.) 




000016 


116716 
000007 


.IIP NB 


<7> 


MOVB 7»(6.) 




000022 


013746 
000054 




Moy 


e#"054.-(6. ) 




000026 


062716 
000360 




APD 


»''0360i (6. ) 




000032 


004736 




JSR 


7. 18(6. )+ 


25 


000034 


152760 
000017 
000342 




BISB 


*BMASKrBITMAP(RO) (PROTECT NEW CONSOLE 
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Figure 5-3: Program to Switt;h the Console Terminal (Cont.) 



26 












27 


000042 


062700 
000304 




ADD 


»304>R0 


28 










' 


29 


000046 


012701 
000206 




MOV 


tCSR)Rl 


30 












31 


000052 


005070 
000000 




CLR 


e(RO) 


32 












33 


000056 


012120 


i«: 


MOV 


(Rl)+r (R0)+ 


34 












35 


000060 


005711 




TST 


0R1 


36 


000062 


100775 




BMI 


1$ 


37 












38 


000064 


012700 
000060 




MOV 


♦60, RO 


39 












40 


000070 


011101 




MOV 


eRl.Rl 


41 




000004 




• REPT 


4 


42 








MOV 


(R0)+, (R1)+ 


43 








.ENDR 






000072 


012021 




MOV 


<RO)+><R1)+ 




000074 


012021 




MOV 


(RO)+,<R1)+ 




000076 


012021 




MOV 


<R0)+,<R1)+ 




000100 


012021 




MOV 


<RO)+r <R1)+ 


44 


000102 






.MTPS 







000102 


005046 


.IIF 


NB <0> 


CLR -(6.) 




000104 


116716 
000000 


• IIF 


NB <0> 


MOVE 0,<6.) 




000110 


013746 

000054 




MOV 


e»"054r-<6. ) 




000114 


062716 
000360 




ADD 


*"0360i (6. ) 




000120 


004736 




JSR 


7. re(6. )+ 


45 


000122 






.EXIT 






000122 


104350 




EMT 


"0350 


46 












47 


000124 




2*! 


.PRINT 


♦ NOMT 




000124 


012700 
000134' 




MOV 


*N0MT,Z0 




000130 


104351 




EMT 


-0351 


48 


000132 






.EXIT 






000132 


104350 




EMT 


"0350 


49 












50 








.NLIST 


BEX 


51 


000134 


077 


NOMTI 


! .ASCIZ 


/TMULTI-TERMIN 


52 








.EVEN 




53 












54 


000206 


175620 


CSR! 


.WORD 


CSRAD 


55 


000210 


175622 




.UORD 


CSRAD+2 


56 


000212 


175624 




. UORD 


CSRAD+4 


57 


000214 


175626 




.UORD 


CSRAD+6 


58 


000216 


000310 




.UORD 


VEC 


59 




000000' 




.ENia 


PR0C3 



(VECTORS 

rRO => CONSOLE REGISTER 

(LIST IN RMON 

JRl => NEW CSR/DATA 

(REG LIST 

fDISABLE OLD INPUT CSR 

JINTERRUPTS 

(MOVE IN NEW CSR/DATA 

(REGISTER ADDR 

(DONE? 

(IF MINUS, NO. . . 

(DO ANOTHER 

(RO = PRESENT CONSOLE 

(VECTOR 

(Rl = NEW VECTOR 

(LOAD NEW CONSOLE VECTORS 

(LOAD NEW CONSOLE VECTORS 

(LOAD NEW CONSOLE VECTORS 

(LOAD NEW CONSOLE VECTORS 

(LOAD NEW CONSOLE VECTORS 

(BACK TO PRIORITY 



(TERMINATE PROGRAM 



(PRINT ERROR MESSAGE 



AND LEAVE 



(CSR/DATA BUFFER/VECTOR LIST 



SYMBOL TABLE 



BITMAP= 000342 
BMASK = 000017 
CSR 000206R 



CSRAD = 175620 
MTTY* =.- 020000 
NOMT 0001134R 



PR0C3 OOOOOOR 
SYSGEN= 000372 
VEC = 000310 



. ABS. 


000000 


000 




000220 


001 


ERRORS 


detected: 






virtual memory USED! 8448 WORDS ( 33 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 56 PACIES 
rV4!C0NSOL/L!MEB/L!TTM=V4!CONSOL 
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5.4.3 A Separate Terminal for Each Job i 

Once you perform a system generation for the multi-terminal feature, you 
can easily establish private consoles for up to eight jobs. Of course, you 
must be running an FB or XM monitor with the system job feature in order 
to support more than two jobs. 

As Section 5.3 describes, simply use the FRUN/TERMINAL:n or SRUN/ 
TERMINAL:n commands to start foreground and system jobs, and assign 
them to private consoles. You need not use any multi-terminal programmed 
requests to do this. Remember that each console is truly private — no two 
jobs can share terminals through the FRUN or SRUN /TERMINAL:n 
mechanism. 

Each job can attach its own console terminal and issue subsequent multi- 
terminal programmed requests. 

4 

5.4.4 Multi-Terminal Applications 

Some applications need to take advantage of RT-ll's multi-terminal 
feature by using the programmed requests to manage more than one ter- 
minal per job. Typical DIGITAL applications include MU BASIC-11, 
CTS-300, and FMS-11. These represent applications in which one program 
controls several terminals. Jobs that must control more than one terminal 
use the multi-terminal data structures and programmed requests. 

5.5 Introduction to Multi-Terminal Programmed Requests 

It is not difficult for a program to use more than one terminal in a multi- 
terminal system. Table 5-1 summarizes the actions a program may need to 
take in order to use a terminal in addition to its own console terminal. It 
also lists the appropriate procedures for the program to follow. Familiarize 
yourself with the procedures and the corresponding progranuned requests. 
The RT-11 Programmer's Reference Manual provides detailed information 
on the format of each programmed request. Study this information before 
you attempt to write a multi-terminal application program. 

Table 5-1: Summary of Activities for a Program in a Multi-Terminal 
System 

Activity Procedure to Follow 

Obtain the status of a multi- Use the .MTSTAT programmed request, 
terminal system. 

Acquire a terminal. Use the .MTATCH programmed request to attach the 

terminal and dedicate it to this program. As part of its 
startup procedure a program usually attaches all the 
terminals it needs. Note that only one job can attach a 
shared console, and only the terminal's owner can issue i 

multi-terminal programmed requests for it. However, 
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Table 5-1: Summary of Activities for a Program in a Multi-Terminal 
System (Cont.) 



Activity 



Procedure to Follow 



Examine the characteristics of 
each attached terminal. 

Change terminal character- 
istics if necessary. 

Get a character from a terminal 
and wait for it. 

Get a character from a terminal; 
do not wait for it. 



Send a character to a terminal 
and wait for it. 

Send a character to a terminal; 
do not wait for it. 



Send a line to a terminal; wait 
until it prints. 

Reset CTRL/0 for a terminal, 
enabling output. 

Relinquish ownership of a ter- 
minal so that another job can 
use it. 



all the jobs sharing the background console can issue 
.TTYIN, .TTYOUT, .CSIGEN, .CSISPC, .GTLIN, and 
.PRINT requests for it, as well as .READ and .WRITE 
requests for TT. 

To detect status changes without issviing a program- 
med request, examine the AST word for each terminal. 

Use the .MTGET programmed request. 



Use the .MTSET programmed request. 

Use the .MTIN programmed request. 

Use .MTSET to set the status word, then use the 
.IVITIN programmed request. (You need issue the 
.]V[TSET only once.) 

Use the .MTOUT programmed request. 

Use .MTSET to set the status word, then use the 
.MTOUT programmed request. (You need issue the 
.MTSET request only once.) 

Use the .MTPRNT programmed request. 
Use the .MTRCTO programmed request. 
Use the .MTDTCH programmed request. 



5.6 Multi-Terminal Data Structures 

The following sections describe the two important data structures for 
multi-terminal systems: terminal control blocks, and asynchronous ter- 
minal status words. 



5.6.1 Terminal Control Bloctk (TCB) 

RT-ll creates one terminal control block, called a TCB, for each terminal 
you describe at system generation time. Each TCB located in the Resident 
Monitor contains terminal characteristics, terminal status, and the input 
and output ring buffers and pointers for the terminal. The length of a TCB 
varies depending on the special features you select through system genera- 
tion. Note, though, that the first 20 decimal words in each TCB are fixed. 
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5.6.1.1 Format — Figure 5-4 illustrates the format of the TCB; Table 5-2 
describes its contents. An asterisk {*) marks the data structures whose size, 
offset, or existence depends on the special features you select through 
system generation. 

Figure 5-4: Format of the Terminal Control Block (TCB) 



T.CNFG 



T.CNF2 



T.FCNT 



T.TFIL 



T.WID 



T.LPOS 



T.OCHR 



T.OWNR 



T.STAT 



T.CSR 



T.VEC 



T.PRI 



T.PUN 



T.JOB 



T.PTTI 



T.NFIL 



T.TNFL 



T.TCTF 



T.TID 



T.TTLC 



T.IRNG 



T.IPUT 



T.ICTR 



T.IGET 



T.ITOP 



INPUT RING 

(DEFAULT SIZE ^ 

134 BYTES) 



T.OPUT 



T.OCTR 



T.OGET 



T.OTOP 



OUTPUT RING 

(DEFAULT SIZE = 

40 BYTES) 



T.RTRY 



T.TBLK 
(7 WORDS) 



T.AST 
(2 WORDS IN XM) 



T.XCNT 



T.XFLG 



T.XPRE 



T.XBUF 
(3 WORDS) 



T.CNT 
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Table 5-2: Contents of the Terminal Control Block (TCB) 
Offset Name Description 







T.CNFG 



T.CNF2 



T.TFIL 



T.FCNT 



T.WID 



10 


T.OCHR 


11 


T.LPOS 


12 


T.OWNR 



14 


T.STAT 


16 


T.CSR 


20 


T.VEC 


22 


T.PRI 


24 


T.JOB 



The terminal configuration word. A program and the 
monitor communicate with each other about terminal 
characteristics through the .MTGET and .MTSET pro- 
grammed requests. These requests use a four-word status 
block within the program to store terminal information. 
The first word, M.TSTS, has the same structure as 
T.CNFG. Table 5-3 describes the meaning of each bit in 
T.CNFG. 

The second terminal configuration word. The structure of 
this word is the same as that of M.TST2, the second word of 
the four-word status block for .MTGET and .MTSET pro- 
grammed requests. Table 5-4 describes the meaning of each 
bit in T.CNF2. 

Contains the character after which this terminal requires 
one or more fill characters. The counterpart of this byte in 
the four-word status block for .MTGET and .MTSET pro- 
grammed requests is called M.TFIL. 

Contains the number of fill characters that this terminal re- 
quires. The counterpart of this byte in the four-word status 
block for .MTGET and .MTSET programmed requests is 
called M.FCNT. 

Contains the carriage width of this terminal. The counter- 
part of this word in the four-word status block for .MTGET 
and .MTSET programmed requests is called M.TWID. The 
maximum value is 255 decimal. 

Contains the character to output. 

Contains the current carriage position for this terminal. 

A pointer to the impure area of the job that currently owns 
this tei-minal. This word has a value when this terminal is a 
private! console for a job, or, when it is a shared console and 
one joti has attached it. This word is when this terminal is 
a shared console and no job has attached it, or when it is not 
a console and no job has attached it. This word is simply 
nonzero in an SJ system if the job issues an .MTATCH re- 
quest. 

Contains the terminal status. Table 5-5 describes the mean- 
ing of (3ach bit in T.STAT. 

Contains the CSR for the keyboard of this terminal. It is 
if the bootstrap could not find the CSR; this makes the 
LUN unusable. 

Contauis the first interrupt vector for this terminal. 

Contains the device interrupt priority. 

Contains the job number of the job that currently owns this 
terminal. 
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Table 5-2: Contents of the Terminal Control Block (TCB) (Cont.) 

Offset Name Description 



25 



26 



52 



T.PUN 



T.NFIL 



27 


T.PTTI 


30 


T.TCTF 


31 


T.TNFL 


32 


T.TID 



di 




36 


T.TTLC 


40 


T.IRNG 


42 


T.IPUT 


44 


T.ICTR 


46 


T.IGET 


50 


T.ITOP 



T.OPUT 
T.OCTR 



T.OGET 
T.OTOP 



T.RTRY 



Contains the physical unit number of this terminal. This 
value is always for terminals on DL interfaces. For ter- 
minals on DZ interfaces, the value ranges from through 7 
(0 through 3 for DZVlls). 

Active fill character counter. This byte contains the 
number of nulls left to print. 

Contains the last character typed on the terminal keyboard. 

Contains the special fill character. (For example, a space is 
the special fill character for a tab, and a line feed is the 
special fill character for a form feed.) 

Contains the count for the special fill character. The value 
is stored as a negative number. 

A pointer to the terminal identification prompt string, 
which contains the job name, and which is used only when 
the monitor is actually printing an identification. It is at 
all other times. 

Reserved. 

Contains the terminal line count (the number of lines in the 
input buffer). 

A pointer to the first byte of the input ring buffer. (For 
more information on ring buffers, see Chapter 3.) 

Input PUT pointer. 

Input character count. 

Input GET pointer. 

Indicates the top of the input ring buffer. This word points 
to the byte just beyond the high limit of the buffer. 

Input ring buffer. Its length is determined at system 
generation time. It is TTYIN bytes long. 

Output PUT pointer. 

Output character count. 

CTRL/0 flag. A value of means CTRL/0 is not in effect; a 
value of 1 means that CTRL/0 is in effect. 

Output GET pointer. 

Indicates the top of the output ring buffer. This word ac- 
tually points to the byte just beyond the high limit of the 
buffer. 

Output ring buffer. Its length is determined at system 
generation time. It is TTYOUT bytes long. 

Present if device time-out support or support for modems 
was selected at system generation time. This word contains 
the retry count for output. 
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Table 5-2: Contents of the Terminal Control Block (TCB) (Cont.) 
Offset Name Description 

T.TBLK Present if device time-out support or support for modems 

was selected at system generation time. This seven-word 
area is the time-out block for this terminal. 

T.AST Present if the assmchronous terminal status word was 

selected at system generation time. This word is a pointer 
to the AST word. In XM systems, the AST pointer is 
followed by a second word that contains a PARI value for 
mapphig to the AST word. 

T.XFLG Present if the system job feature was selected at system 

generation time. If this flag byte is nonzero, it indicates 
that a CTRL/X sequence is in progress. 

T.XCNT Present if the system job feature was selected at system 

generation time. This byte contains the number of 
characters typed in a CTRL/X sequence. 

T.XPRE Present if the system job feature was selected at system 

generation time. This word contains the previous character 
typed on the terminal keyboard. 

T.XBUF Present if the system job feature was selected at system 

generation time. This three-word area contains the 
characters typed as part of a CTRL/X sequence. 

T.CNT Present if the system job feature was selected at system 

generation time. This word contains the number of jobs 
that are sharing the background console. 



Table 5-3: Terminal Configuration Word, T.CNFG 
Bit Meaning 



Hardware tab bit. When set, it indicates that this terminal has hardware 
tab support. The monitor does not convert a tab character to spaces 
before sending it to <;he output ring buffer. Your program can set this bit 
for a particular terminal through the .MTSET programmed request 
(described in Section 5.7.3). The SET TT: TAB command sets this bit for 
the background console. 

When this bit is set, the monitor sends a carriage return/line feed com- 
bination to the terminal when its carriage width is exceeded. Your pro- 
gram can set this bit for a particular terminal through the .MTSET re- 
quest. The SET TT; CRLF command sets this bit for the background 
console. 

Hardware form feed bit. When set, it indicates that this terminal has 
hardware form feed support. The monitor does not convert a form feed 
character to line feeds before sending it to the output ring buffer. Your 
program can set this bit for a particular terminal through the .MTSET 
programmed request;. The SET TT: FORM command sets this bit for the 
background console. 
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Table 5-3: Terminal Configuration Word, T.CNFG (Cont.) 

Bit Meaning 



3 When this bit is clear, the monitor treats CTRL/F, CTRL/B, and 

CTRL/X as ordinary characters and ignores their special meanings. The 
SET TT: NOFB command clears this bit for the background console. 
Your program cannot set this bit for other terminals; only the shared 
console can use it. 

4-5 Reserved. 

6 The inhibit TT wait bit. It is similar to bit 6 in the Job Status Word, 
which a program can set. When this bit is set, the program does not wait 
for I/O to complete on the terminal before execution continues. Note that 
bit 6 in the JSW affects only the job's current console; it does not affect 
any other terminals attached to this job. If the program uses other ter- 
minals for I/O, it can set this bit in each TCB by using the .MTSET pro- 
grammed request. 

If this terminal is a private console for this job, the job can set bit 6 in 
the JSW. In a multi-terminal application, the job can set bit 6 in either 
the JSW or in the TCB for the console terminal. In any case, setting bit 6 
in one place (the TCB or the JSW) results in both bits being set. 

7 The XON/XOFF bit. When set, it enables recognition of the XON 
(CTRL/Q) and XOFF (CTRL/S) characters. The SET TT: PAGE com- 
mand sets this bit for the background console. (See Chapter 3 for more 
information on XON/XOFF processing.) 

8-11 The ba ud rate mask f or terminals on DZ lines. (The baud r at e f or ter- 

minals on DL lines is not programmable through the .MTSET request.] 
The values are as follows: 

Mask Rate 



0000 


50 


0400 


75 


1000 


110 


1400 


134.5 


2000 


150 


2400 


300 


3000 


600 


3400 


1200 


4000 


1800 


4400 


2000 


5000 


2400 


5400 


3600 


6000 


4800 


6400 


7200 


7000 


9600 


7400 


not used 



12 The special mode bit. It is similar to bit 12 in the Job Status Word, 

which affects the job's console. If this terminal is a private console for 
this job, the job can set bit 12 in the JSW to enable special mode. In a 
multi-terminal application, the job can set bit 12 in either the JSW or in 
the TCB for the console terminal. In any case, setting bit 12 in one place 
(the TCB or the JSW) results in both bits being set. (See the description 



5-16 Multi-Terminal Feature 



Table 5-3: Terminal Configuration Word, T.CNFG (Cont.) 
Bit Meaning 

of .TTYIN in the RT-11 Programmer's Reference Manual for more in- 
formation on special mode.) If the program uses other terminals for I/O, 
it can set this bit in each TCB by using the .MTSET programmed 
request. 

13 The remote terminal bit. It is read-only, and your program cannot alter 
it. When set, this bit indicates that this terminal is remote. 

14 When this bit is set, lower- and upper-case typing is enabled. When this 
bit is clear, the monitor converts all typed characters to upper-case. If 
this terminal is a iprivate console for this job, the job can set bit 14 in the 
JSW. In a multi-terminal application, the job can set bit 14 in either the 
JSW or in the TCB for the console terminal. In any case, setting bit 14 in 
one place (the TCB or the JSW) results in both bits being set. 

15 When this bit is set, the monitor takes the appropriate action for a video 
terminal when the DELETE key is pressed. Your program can set this 
bit for a particular terminal through the .MTSET programmed request. 
The SET TT: SCOPE command sets this bit for the background console. 



Table 5-4: Second Terminal (Configuration Word, T.CNF2 

Bit Meaning 

0-1 These two bits indicate the length of a character. The DZl 1 can transmit 

characters that are five, six, seven, or eight bits long. The values are as 
follows: 

Value Character Length 

00 5 bits 

01 6 bits 

10 7 bits 

11 8 bits 

These bits are unused for DL interfaces. 

2 Unit stop bit. Depending on the speed, it indicates the number of stop 
bits to send. The values are as follows: 

= send one stop bit 

1 = send two stop bits (one and one-half stop bits if five-bit characters 

are used) 

This bit is unused for DL interfaces. 

3 The parity enable bit. When set, it enables parity checking. 

4 Indicates whether parity checking will be odd or even. The values are as 
follows: 

Value Parity Checking 

even parity 

1 odd parity 

This bit is unused for DL interfaces. 
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Table 5-4: Second Terminal Configuration Word, T.CNF2 (Cont.) 

Bit Meaning 



5-6 Reserved. 

7 When set, this bit indicates "read pass-all" mode. In this mode, RT-U 

transmits all eight bits of each character without interpreting or echoing 
the characters. This feature is often referred to as "transparency." For 
example, it passes - C as 203 in "read pass-all" mode if the terminal sets 
the high bit upon transmission. If set, the terminal is impUcitly in single- 
character mode. 

8-14 Reserved. 

15 When set, this bit indicates "write pass-all" mode. In this mode, RT-11 

transmits all eight bits of each character without interpreting the 
characters. 



Table 5-5: Terminal Status Word, T.STAT 

Bit Meaning When Set 



Indicates that a fill sequence is in progress. 

1-3 Reserved. 

4 Indicates that a detach operation is in progress. Input from the terminal 
is ignored. 

5 This is the TT handler synchronization bit. 

6 Indicates that an output interrupt is expected. 

7 Indicates that the terminal has sent XOFF to request suspension of 
output. 

8-9 Reserved. 

10 Indicates that this terminal is the shared console. 

11 Indicates that the remote terminal has hung up. 

12 Indicates that the terminal interface is a DZ. 

13 Reserved. 

14 Indicates that two CTRL/Cs were typed at this terminal. This bit is reset 
by .MTGET. 

1 5 Indicates that this terminal is a console for some job. It can be shared or 
private. 



5.6.1.2 Patching a TCB — You can use SIPP to make binary patches to the 
terminal control blocks in your monitor file, :«;;c;c;c;c;c.SYS. The TCBs are 
located in p-sect MTTY$, which you can find on your monitor link map. 
They appear in the same order in which SYSGEN assigned physical units 
to logical unit numbers at system generation time (see Section 5.2). The 
first TCB is for LUN 0; it starts at the label DLTCB::. The TCBs are all the 
same size; TCBSZ contains their length. 
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5.6.2 Asynchronous Terminal Status (AST) Word 

The asynchronous terminal status (AST) word is a special feature that you 
can select at system generation time. If you select this feature, you can set 
aside space for one AST word per LUN in your own program. Then, when 
you issue the .MTATCH programmed request to attach a terminal to your 
job, you specify as an argument; the address of the AST word for that ter- 
minal, The purpose of the AST word is to monitor each terminal's Une so 
that the program can obtain cert;ain information without issuing a program- 
med request. RT-11 sets or clears bits in the AST word as significant 
events occur. The AST word contains information on whether: 

• Input is available from the terminal 

• The terminal's output ring buffer is empty 

• Double CTRL/C was typed on the terminal 

• A remote line just dialed in or just hung up 

Table 5-6 shows the event flags in the AST word and their meaning. Unus- 
ed bits are reserved for future vise by DIGITAL. 



Table 5-6: Asynchronous Terminal Status (AST) Word 

Bit Name Bit Pattern Meaning When Set 



15 



AS.CTC 



100000 



14 


AS.INP 


40000 


13 


AS.OUT 


20000 


7 


AS.CAR 


200 


6 


AS.HNG 


100 



Double or multiple CTRL/C was typed on 
this terminal. You must reset this bit; the 
monitor never turns it off. 

Input is available from this terminal. 

The output ring buffer is empty. 

Carrier is present (for remote Unes only). 

This remote line just hung up and RT-11 
dropped it. 



The monitor sets bit 15, AS.(I!TC, whenever two or more consecutive 
CTRL/Cs are typed on any terminal. Typing two CTRL/Cs on a job's con- 
sole terminal always aborts the job, unless the job already issued the 
.SCCA programmed request to intercept the characters. The job must reset 
this bit before it continues processing. 

The monitor sets bit 14, AS.INP', when input is available from the terminal. 
It can be a line of characters in normal mode, or a single character in special 
mode. The monitor clears this bit when the program reads the characters. 

The monitor sets bit 13, AS.OUT, when the terminal's output ring buffer is 
empty. This occurs after the last character in the ring buffer is printed on 
the terminal. The monitor clears this bit when there are characters in the 
ring buffer. 
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The monitor sets bit 7, AS.CAR, when it answers a remote line. It clears 
this bit when the remote line hangs up or drops carrier. Carrier is a tone 
transmitted over the remote Une. It carries information through its 
modulation. 

The monitor sets bit 6, AS.HNG, when it drops a remote Une that just 
hung up. 

5.7 Using the Multi-Terminal Programmed Requests 

The routines in MTTEMT, which are part of the Resident Monitor, 
dispatch the multi-terminal programmed requests and process them. 

The dispatch routine accepts programmed requests that translate into 
EMT 375 instructions with a subcode of 37 and a function code in the range 
through 10 octal. The dispatch routine first checks to see if the 
programmed request is a valid one. Then it verifies the logical unit number 
and makes sure that the terminal is installed. If the programmed request is 
for an attach operation, the dispatch routine verifies that the terminal is not 
already attached. For all other requests, the dispatch routine verifies that 
the terminal is attached to the calling program. 

If the request passes all the checks in the dispatch routine, control passes 
to the EMT processing code for the individual request. 

5.7.1 Attaching a Terminal: .l\/ITATCH 

Issue the .MTATCH programmed request to attach a terminal to your job. 
This permits your program to print characters on the terminal, get 
characters from it, and alter its characteristics. 

When a job attaches a terminal, the terminal remains attached until the job 
issues a .MTDTCH request, or until the job exits or aborts. If the terminal 
is detached through the .MTDTCH request, the job is blocked until output 
in process for the terminal finishes and the monitor detaches the terminal. 
If the terminal is detached when the job aborts, the output terminates and 
the monitor detaches the terminal immediately. 

The attach routine first checks to see if the terminal is the shared console, 
but not this job's console. If so, the routine issues error code 4. If the ter- 
minal is already attached to another job, the routine also issues error code 4. 
No other errors can occur in the attach operation. 

The routine attaches the terminal by setting up two words in the TCB for 
this terminal. In FB and XM systems, it stores the job number in T.JOB. In 
SJ systems, T.OWNR is made nonzero when the terminal is attached. In 
FB and XM systems, T.OWNR contains a pointer to the owning job's im- 
• pure area. 

t 

If AST support is part of the system, the routine puts a pointer to the AST 
word in T.AST. In XM systems, it also stores a value in T.AST -I- 2 to be 
used as a PARI value in mapping to the AST word. 
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The routine next moves some bits from the JSW into T.CNFG, if this ter- 
minal is the job's console. It copies bits 14 (for lower case), 12 (special 
mode), and 6 (wait inhibit). If j;he terminal is the background console the at- 
tach routine loads T.TFIL from location 56. 

5.7.2 Getting Terminal Status: .IVITGET 

Issue the .MTGET programmed request to obtain the status of a terminal. 
(The terminal need not be attached to your program in order to obtain the 
status.) 

The .MTGET routine moves information from the TCB to the status block 
in your program. The following transfers occur: 

T.CNFG to M.TSTS 

T.CNF2 to M.TST2 

T.TFIL to M.TFIL 

T.FCNT to M.FCNT 

T.WID to M.TWID 

high byte of T.STAT to M.TSTW 

Then, if the terminal is not attached to any job, the routine returns error 
code 1. If the terminal is attached, but not to this job, the routine returns er- 
ror code 4 and RO contains the job number of the terminal's owner. If the 
terminal is the shared console, but the job has its own private console, RO 
contains the job's own job number. Note that despite the fact that an error 
is returned from this operation, the status information is always placed in 
the status block in your program. 

Finally, if no error was returned, the routine clears bit 14 (CTRL/C) in 
T.STAT. 

5.7.3 Setting Terminal Characteristics: .iVITSET 

Issue the .MTSET programmed request to set the characteristics of a ter- 
minal. If the terminal is not attached to your program, the routine gives er- 
ror code 1. 

The routine moves the contents of M.TSTS to T.CNFG, except for bit 13 
(the remote terminal bit), which is read-only in T.CNFG. If the terminal is 
the job's console, the routine moves some bits from T.CNFG into the JSW. 
It copies bits 14 (for lower casie), 12 (special mode), and 6 (wait inhibit). 

Whether or not the terminal is the job's console, the routine moves the 
following information: 

M.TST2 to T.CNF2 
M.TFIL to T.TFIL 
M.FCNT to T.FCNT 
M.TWID to T.WID 

If DZ support is part of the system, and if this terminal is on a DZ interface, 
the routine waits for any characters to finish printing on this terminal, then 
sets up the DZ Une parameters. 
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NOTE 

Always issue an .MTGET request before an .MTSET re- 
quest. Change only the fields you are interested in. For a 
one-bit field, use a BIS or BIC instruction to set or clear it. 
For a multiple-bit field, clear it first with a BIC and then 
use BIS to load the field. Use MOVB or MOV instructions 
only for byte or word fields. Changing other bits can cause 
unusual terminal service errors. Finally, issue the .MTSET 
specifying the same status block that you used for the 
.MTGET request. 



5.7.4 Getting a Character: .MTIN 

Issue the .MTIN programmed request to get a character from the terminal. 

The routine moves some bits from the JSW into T.CNFG if this terminal is 
the job's console. It copies bits 14 (for lower case), 12 (special mode), and 6 
(wait inhibit). If the terminal is the background console, the attach routine 
loads T.TFIL from location 56. 

The routine gets a character from the input ring buffer and adjusts the ring 
buffer pointers. If the terminal is the console, the routine uses the ring buf- 
fer in the job's impure area. If the terminal is not the console, the routine 
uses the ring buffer in the terminal's TCB. 

If the input character is CTRL/C on a console terminal, and .SCCA is not in 
effect, the job aborts. 

5.7.5 Printing a Character: .IVITOUT 

Issue the .MTOUT programmed request to print a character on the 
terminal. 

The routine moves some bits from the JSW into T.CNFG if this terminal is 
the job's console. It copies bits 14 (for lower case), 12 (special mode), and 6 
(wait inhibit). If the terminal is the background console, the attach routine 
loads T.TFIL from location 56. 

The routine moves a character from the user buffer into the output ring buf- 
fer and adjusts the ring buffer pointers. If the terminal is the console, the 
routine uses the ring buffer in the job's impure area. If the terminal is not 
the console, the routine uses the ring buffer in the terminal's TCB. 

5.7.6 Printing a Line: .IWiTPRNT 

Issue the .MTPRNT programmed request to print a string of characters on 
the terminal. The string can end with a null byte (to print a carriage return 
and a Une feed at its end) or a 200 octal byte, just as in the .PRINT program- 
med request. 
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The routine moves a line from the user buffer into the output ring buffer 
and adjusts the ring buffer pointers. If the terminal is the console, the 
routine uses the ring buffer in the job's impure area. If the terminal is not 
the console, the routine uses tllie ring buffer in the terminal's TCB. If there 
is no room in the output ring, the job is blocked until room is available, 
regardless of the value of bit 6 in T.CNFG. 

5.7.7 Resetting CTRL/0: .MTRCTO 

Issue the .MTRCTO programmed request to enable output on a terminal 
even though CTRL/0 may have been typed. 

This routine clears the CTRL/O flag in the TCB for the terminal and moves 
some bits from the JSW into T.CNFG if this terminal is the job's console. It 
copies bits 14 (for lower case), 12 (special mode), and 6 (wait inhibit). If the 
terminal is the background console, the attach routine loads T.TFIL from 
location 56. 

If you ever alter the contents of the JSW, DIGITAL recommends that your 
program issue the .MTRCTO request immediately afterward so that the 
TCB and the JSW always have the same information. In particular, if you 
require lower-case input for a .GTLIN request, set bit 14 in the JSW and 
issue .MTRCTO or .RCTRLO before using .GTLIN. 

5.7.8 Getting System Status: .l\/ITSTAT 

Issue the .MTSTAT programmed request to obtain status information 
about the multi-terminal system. This request returns the following four 
words of information to your program: 

• The offset from the start of the Resident Monitor to the first TCB 

• The offset from the start of the Resident Monitor to the TCB of the current 
console terminal for this job 

• The value of the highest TCB (equivalent to the highest LUN) 

• The size of each TCB in bytes (Note that all TCBs are the same size.) 

Remember that the TCBs are located in the Resident Monitor in the order 
in which you specified your DL and DZ lines to the SYSGEN dialogue. That 
is, the TCBs for local DLs appear first, followed by remote DLs, local DZs, 
and remote DZs. 

With the information returned to you by .MTSTAT you can find the TCB 
for any terminal in the system and examine its contents with the .GVAL re- 
quest. Figure 5-4 and Table 5-2 describe the contents of each TCB. 

5.7.9 Detaciiing a Terminal: .IVITDTCH 

Issue the .MTDTCH programmed request to detach a terminal from your 
job and make it available for use by another job. 
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The routine first sets the DTACH$ bit, bit 4, in T.STAT to indicate that a 
detach operation is in progress. This avoids any race conditions in the 
module MTTINT. (A race condition is a situation in which two or more proc- 
esses attempt to modify the same data structure at the same time; as a 
result, the data structure is corrupted and the integrity of the processes is 
compromised.) It then forces XON if XOFF had been previously set. If the 
terminal is not a shared console, the output buffer is then flushed. In SJ, 
the routine loops until T.OUTR is clear. In FB and XM, the job is blocked 
until T.OCTR is clear. 

The words T.OWNR and T.AST are set to zero to detach the terminal. 
DTACH$ is finally cleared to finish the operation. 

Whenever a job aborts, terminals attached to it are detached without hav- 
ing their buffers flushed. 

5.8 Summary of Multi-Terminal Programmed Request Error Codes 

Table 5-7 summarizes the error codes that the multi-terminal programmed 
requests can put into byte 52. Table 5-8 shows which error codes each pro- 
grammed request can generate. 

Table 5-7: Multi-Terminal Programmed Request Error Codes and 
Meanings 

Byte 52 
Code Meaning 



There is no character in the input ring buffer for this terminal; or, there 
is no room in the output ring buffer for this terminal. 

1 The logical unit number is invalid. 

2 The logical unit number does not exist. 

3 The programmed request you issued is invalid. The function code for 
EMT 375, subcode 37, must be in the range through 10 octal. 

4 This terminal is already attached to another job. The program cannot at- 
tach it, detach it, or set its status. 

5 The user buffer address, the status block, or the AST word address is 
outside the vaHd addressing space for this program. This error occurs in 
XM systems only. 



Table 5-8: Summary of Error Codes 

Programmed Error Code 



Request 12 3 4 5 



.MTATCH X X X X 

.MTGET X X X X X 

.MTSET XXX X 
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Table 5-8: Summary of Erroir Codes (Cont.) 

Programmed Error Code 



Request 12 3 4 5 



.MTIN X X X X X 

.MTOUT X X X X X 

.MTPRNT XX X 

.MTRCTO XXX 

.MTSTAT X 
.MTDTCH XXX 



5.9 The Console as a Special Case 

The console terminal is always a special case for I/O in multi-terminal 
systems. Recall that each job has input and output ring buffers and 
pointers, both in its console's TCB and in its impure area. Whenever a job 
gets characters from its console terminal, or writes characters to it, the 
monitor uses the set of ring buffers located in the job's impure area. In this 
case, the console can be the background console, if this job is sharing it, or it 
can be a private console, if this job has one. 

For all I/O requests involving the job's console, the monitor performs the 
request based on the characteristics indicated in the Job Status Word 
rather than in the terminal configuration word. However, if you set or clear 
a terminal-related bit in the JSW, the monitor automatically sets or clears 
the corresponding bit in the terminal configuration word for the job's con- 
sole the next time the job does any kind of input or output request or reset 
CTRL/0 request for that terminal (see Table 5-3). DIGITAL recommends 
that you issue the .MTRCTO request immediately after altering the JSW to 
make sure that the contents of the JSW are duplicated in the TCB for the 
terminal. Similarly, if you modify the terminal configuration word with 
.MTSET for a job's console, the monitor also modifies the JSW. 

On entry to the EMT processor, R3 contains a pointer to the job's TCB, and 
R5 contains a pointer to the irapure area. 

Note that a program must issue the .SCCA programmed request to inhibit 
CTRL/C on its console termimil. 



5.10 Interrupt Service 

Terminal service in multi-terminal systems is centraUzed in the routines 
contained in MTTINT. This source file is assembled and Unked together 
with other files to become part, of the Resident Monitor. 

In generM, RT-11 services terminals in one of two ways, depending on 
whether the terminal is connected through a local or a remote line. 
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5.10.1 Local Terminals 

Local terminals are connected to an interface by a minimum of four wires: 

• Receive data • Transmit data 

• Receive ground • Transmit ground 

Some interface circuitry, such as the EIA RS232-C, combines the receive 
ground and transmit ground into one signal ground; for these, a minimum 
of three wires is required. In addition, PDT-11 terminal ports require that 
the data terminal ready signal be connected and asserted for proper 
operation. 

RT-ll's interrupt service routine for multi-terminal systems contains the 
following data structures: 

• Receive CSR I/O page address 

• Receive data buffer I/O page address 

• Transmit CSR I/O page address 

• Transmit data buffer I/O page address 

RT-ll's interrupt service is essentially simple. The bootstrap sets the in- 
put (or receiver) interrupt enable bit; the monitor leaves it set at all times. If 
a character is typed on a local terminal, an interrupt occurs and the monitor 
picks up the character. If the terminal is not attached to any job, the 
character is ignored. In multi-terminal systems with time-out support, the 
monitor turns on the interrupt enable bit for each DL once every 30 clock 
ticks. 

The monitor only sets the output interrupt enable bit when it is ready to 
print a character. It clears the bit after the output ring buffer is empty. 

5.10.2 Remote Terminals 

Remote terminals are connected to RT-11 through modems (also known as 
data sets) and telephone lines so that someone can call up the computer and 
ring its data phone. When this occurs, it causes an interrupt, which the 
monitor recognizes. If the unit is attached, the multi-terminal service 
routine answers the phone call and sends out carrier in response. (Carrier is 
a tone transmitted over the remote line that carries information through its 
modulation.) 

The remote terminal can communicate with RT-11 through an approved 
protocol. Essentially, the terminal must send its own carrier to the com- 
puter. If the terminal immediately sends carrier, RT-11 recognizes the 
signal, and I/O can begin. If, however, the terminal does not send its own 
carrier immediately, RT-11 sets a 30-second timer. This time interval gives 
someone an opportunity to place a telephone receiver into an acoustic 
coupler. If the terminal does not send carrier within 30 seconds, RT-11 
disconnects the line. 
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Once communication has begun, RT-11 never takes the initiative to ter- 
minate the connection. It always continues to send carrier. However, there 
are two situations in which RT-11 does hang up on the remote line. If the 
terminal stops sending carrier for any reason, RT-11 waits two seconds for 
it to resume. When the interval expires, RT-11 hangs up on the remote line. 
In the other situation, the remote terminal hangs up. RT-11 detects loss of 
carrier and waits two seconds before disconnecting the remote line. Special 
requirements for customers in the United Kingdom are met through 
assemblies based on the U.K. conditional being set to 1. 

Remote terminals require a DLll-E, DLVll-E (or equivalent, such as the 
PDT-11 modem port), or DZ interface. In addition to the data lines required 
for remote terminals, the following control lines must be connected: 

• data terminal ready 

• ring indicator 

• carrier detect 

A local terminal can be connected to a remote terminal interface if it is iden- 
tified during system generation as a local terminal. The control lines listed 
aboA^e are then ignored and you can leave them unconnected. 



5.11 Polling Routines 



RT-11 's multi-terminal support includes two polling routines, which the 
following sections describe. 

5.11.1 Time-Out Routine for DL Terminals 

You can select the time-out polling routine as a special feature at system 
generation time. It is an example of the device time-out feature that is 
available to application programs through the .TIMIO programmed re- 
quest. RT-11 executes this rouitine once every half second. Its purpose is to 
periodically reenable the I/O interrupt enable bits so that noise on a line or 
local static electricity cannot seriously affect transmissions. 

Every half second, the polling routine examines each DL line on the system. 
It turns on the line's input inttirrupt enable bit and, if the line is remote, its 
modem interrupt enable bit. Thien, if output is pending with no output inter- 
rupt, it turns the output interrupt enable bit off and then on, to force an out- 
put interrupt on the line. (Depiending on the hardware failure that caused 
the loss of the output interrupt, this may occasionally cause a character to 
be repeated.) 

The last thing the time-out routine does is schedule itself to run again. 

5.11.2 DZ Remote Line Poliing Routine 

The DZ polling routine polls the terminals connected to the system through 
DZ interfaces. It is necessary because these terminals do not interrupt 
when their status changes. 
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The remote line polling routine schedules a mark time request. It waits 30 
seconds after the data set rings to detect carrier. If there is no carrier after 
the required amount of time, the routine disconnects the remote line. The 
routine takes similar action on line errors and lost carrier. This routine is 
automatically included in the multi-terminal service for remote DZ lines. 



5.12 Restrictions 



The following restrictions apply to systems with the multi-terminal special 
feature: 

1. Support of the DLll-W interface requires the presence of a REV E or 
later module. In the absence of a REV E module, ECO (Engineering 
Change Order) number DEC-0-LOG M7856-S0002 must be appUed to 
the M7856 module. 

Support of the DLVll-J interface requires the presence of a REV E or 
later module. In the absence of such a module, ECO M8043-MR002 
must be applied to the M8043 module. 

2. The multi-terminal handler can support remote terminals. Modem con- 
trol is available for both DLll-E and DZll interfaces. The DLll con- 
trol answers ring interrupts, permitting terminals to dial in to the 
system. Dial-in is possible with the DZll interface, despite lack of a 
ring interrupt in the DZll, if the modem is operated in auto-answer 
mode. This is achieved through a polling routine that periodically 
checks the status of each line on the multiplexer (see Section 5.11.2). 
Dial-up support for DZ interfaces requires BELL 103 A- type modems 
with "common clear to send and carrier" jumpers installed. With this 
option installed, the modem operates in auto-answer mode. 

3. The hardware console interface must be a DL interface, and it must be 
a local terminal. You can use the SET TT: CONSOL command to move 
the background console to any other local terminal in the system. 

4. The number of DL interfaces RT- 1 1 supports, both local and remote, is 
limited to eight. This number includes the hardware console interface. 

5. The number of DZl 1 controllers is limited to two, for a total of 16 lines. 
The total of DZVll controllers is limited to four, for the same total 
of 16. 

6. The VTll scroller option is disabled when the multi-terminal special 
feature is present in a system. The commands GT ON and GT OFF are 
not valid in multi-terminal systems. For this reason, EDIT cannot use 
the display support. The use of graphics is still supported, though, and 
the display support in TECO works as well. 

7. The maximum input data rate for a single terminal is 300 baud. The ag- 
gregate total input data rate for a system is 4800 baud. 

You can set the output baud rate to any speed; RT-11 sends output as 
fast as possible, depending on the capacity of the CPU and the nature 
of its load. 
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8. When you type double CTllL/C in an SJ system, the monitor does a 
hardware RESET instruction. This causes the DZ multiplexer to reset 

' its status and to drop Data Terminal Ready on all lines, thus hanging 
them up. This action is part of the general cleanup the system performs 
after a program aborts. 

9. li' you plan to devote a terminal to use with the LS handler, do not 
specify the terminal's DL interface in the SYSGEN dialogue for a 
multi-terminal system. Do not attempt to attach the terminal from a 
miulti-terminal application ptrogram, either. 

10. Setting the baud rate, chareicter length, number of stop bits, and pari- 
ty via the .MTSET programmed request is supported only for DZ in- 
terfaces. 

5.13 Debugging a Multi-Terminal Application 

Use VDT, the Virtual Debugging Technique, to debug a multi-terminal ap- 
plication. See Section 4.9 for more information on VDT. 

5.14 IVIulti-Terminal Example Program 

Figure 5-5 shows a program thsit uses the multi-terminal programmed re- 
quests. 

Figure 5-5: Multi-Terminal Exaitnple Program 

MTYSET.MAC - MULTI -TERMINAL INI MACRO V04 . 00 ^-JAN-80 01:47:21 

TABLt; OF conte:nts 

1- 20 Macros 3nd definitions 

2- 1 Start of proaram 

3"- 2 Terminsl ID Loa routinesi error routines 

4- 1 Main terminal setup subroutine 

5- 1 Terminal I/O i Get baud rate routines 

5- 26 Timeout Completion Routine 

6- 1 Baud rate mask I ASCII baud rate tables 

7- ]. Terminal ID tables 

8- 1 Message text 31 Initialization string 

1 .TITLE MTYSET.MAC - MULTI-TERMINAL INITIALIZATION 

;? .ENABL LC 
4 

5 > + 

6 i MULTI-TERMIiMAL INITIALIZATION PROGRAM 

7 ; 

8 ; author: l.c.p. - 10/79 

9 ; 

10 » This FToSraiii will attach all 'known* terminals and 

11 j If they are DIGITAL terminals it will determine at what 

12 i baud rate they are set and put that information in 

13 S their TCEs. ("Foreisn" terminals will be assumed to 

14 ) be set at the correct baud rate). As each terminal is 

15 i 'initialized', its screen will be cleared, a 'sian-on' 

16 i messase will be displaaedr and the terminal type and 

17 ; baud rate will be loa<jed on the background console. 

18 ; - 
19 

20 .SDTTL Macros and definitions 

21 

22 .MCALL .MTATCH, .MTDTCHj .MTGETf .MT0UT» .MTIN 
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Figure 5-5: Multi-Terminal Example Program (Cont.) 
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000004 


S.NTCB 
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000006 
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31 


007400 


MSPEED 
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32 


000100 


TCBIT* 
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100 


33 


010000 


TTSPC* 
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10000 


34 


004000 


HNGUPt 
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4000 


35 


010000 


DZll* 


= 


10000 


36 


020000 


REMOTt 


= 


20000 


37 
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100000 


BKSP 
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100000 


39 


000001 


TAB 
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NOCRLF 
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41 










42 


000012 


LP 
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12 


43 


000015 


CR 


= 


15 


44 


000033 


ESC 


~ 


33 



MTPRNTf .MTSETf .MTSTATr .EXIT 

NT. .TTYOUT. .MRKT. ,CMKT 



(Offset to state word in TCB 

fStst offset to 1st TCB offset 

jStst offset to console TCB 

iStat offset to * TCB (LUN) 

(Stat offset to TCB size 

jB3ud rate mask = bits 8-11 

(Inhibit TT wait 

(TT special bit 

(Terminal had huns ur (offline) 

(DZll 

(DZll line is remote 

(Backspace for rubout ( delete ) 
(Hardware tab 
(*CLEAR* CRLF bit 

(Line feed 
(Carriaae return 
(Escape 



.SBTTL Start of program 
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000026 


016302 
000004 




MOV 


S.NTCB<R3).R2 


(R2 = # of LUNs 
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000032 


001506 




BEG) 


MTEXIT 


(Just CKit if none! 


9 


000034 


016304 
000002 




MOV 


3.CTCB(R3)fR4 


JR4 = Offset to console 


10 
11 


000040 


161304 




SUB 


BR3.R4 ■ 


(TCB 

(R4 = Diff from 1st TCB 


12 


000042 


001410 




BEO 


It 


(No differencei so 


13 












(LUN:0 = console. . . 


14 


000044 


016305 
000006 




MOV 


S.STCB (R3).R5 


(R5 = Size of TCB 


15 


000050 


005001 




CLR 


Rl 


SRI = Quotient 


16 


000052 


005201 


DlVi! 


INC 


Rl 


(Divide diff b« size 


17 












(of a TCB 


18 


000054 


160504 




SUB 


R5.R4 


(to set LUN of console 


19 


000056 


101375 




BHI 


DIV» 


(Repeat until done... 


20 


000060 


010127 




MOV 


R1.(PC)+ 


(Save console LUN... 


21 


000062 


000000 


CLUN! 


• WORD 





(for later reference 


22 


000064 


020267 
177772 


1»! 


CMP 


R2.CLUN 


(Is this the Console? 


23 

24 


000070 
000072 


001465 




BEQ 

.mtatch 


4« 
#AREA»*0.R2 


(Yes. . .already set up 
(Tru to attach terminal 




000072 


012700 
001064' 




MOV 


tAREA>%0 






000076 


012710 
017405 




MOV 


*31. ♦"0400+5. 


1 (0) 




000102 


005060 
000002 




CLR 


2. (0) 






000106 


110260 
000004 




MOVB 


R2f4. (0) 






000112 


104375 




EMT 


"0375 




25 


000114 


103532 




BCS 


MTERRl 


(If carru setr can't ! 
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26 000116 
000116 

000122 

000126 

000132 

000136 

27 000140 

28 000142 



29 000150 

30 000152 



31 000160 

32 000162 



33 000170 

34 000172 



36 000176 
000176 

000202 

000206 

000212 

37 000214 
000214 

000220 

000224 

000232 

000236 
38 

39 000240 

40 000244 

41 000246 

42 000250 
000250 

1 
2 

3 

4 000252 
000252 

000256 

5 000260 

6 000264 
000264 

000270 

7 000272 
8 

9 000274 



012700 

001064' 

012710 

017401 

010360 

000002 

110260 

000004 

104375 

103524 

132763 

000020 

000007 

001451 

132763 

000040 

000007 

001404 

132763 

000010 

000007 

001030 

004767 

000230 



012700 

001064' 

012710 

017404 

010260 

000004 

104375 

012700 

001064' 

012710 

017407 

012760 

001716' 

000002 

110260 

000004 

104375 

004767 
000052 
005302 
100306 

104350 



012700 

001665' 

104351 

004767 

000064 

012700 
001715' 
104351 
000764 

052713 
010100 



.MTGET *AREA,R3,R2 
MOy *AREAf%0 



iGet terminsl ' s status 



3*: 



4»! 



MTEXIT! 



MOV *31.*-0400+lr (0) 

MOV R3>2.(0) 

MOVB R2,4.(0) 

EMT "0375 

BCS MTERR2 (Can't! (Veru Bad!!!) 

BITB *DZ11»/400>M.TSTU(R3) JIs line 3 DZll? 



BEQ 6t (No. . .sssume 3 DLll 

BITB ♦REM0T*/400fM.TSTIJ(R3) (Remote line? 



BEQ 2* (Nope... 

BITB *HNGUP»/400iH.TSTU<R3) (Is it online? 



BNE 5* 
CALL TSETUP 



.MTRCTO *AREArR2 
MOV tAREAiXO 



(Brsnch if not 
(Figure out bsud rate 



i3nd terroinBl type 
(Reset CTRL/0 



MOV #31 .*"0400+4. , (0) 

MOV R2i4.<0) 

EMT "0375 

.MTPRHT *AREAf*HELL0»R2 (Clear screen (if CRT) 

MOV tAREA>%0 

MOV »31.*"0400+7. , (0) 

MOV »HELL0>2.(0) 



MOVB 

EMT 

CALL 

DEC 
BPL 
.EXIT 
EMT 



R2,4. (0) 

"0375 

LOGLUN 

R2 
1« 

"0350 



( and say hello... 

(LoS term ID on console 

(Are we finished? 
(No... So do another LUN 
(We're done... exit 



10 



.SBTTL Terminal ID Loa routines; error routines 

5«! .PRINT ♦OFFLIN (LoS terminal offline 
MOV ♦OFFLIN. XO 



(Include LUN. . . 
( . . .and CRLF 



(Merae . . . 

6*: BIS ♦<TTSPCt!TCBIT«>r(?R3 (DLll - Set the 

(special bits in TCB 



EMT 


"0351 


CALL 


PRNLUN 


.PRINT 


♦ CRLF 


MOV 


♦CRLF.XO 


EMT 


"0351 


BR 


4» 
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11 000300 

12 000304 

13 

14 000310 

15 000314 
16 

17 000316 
000316 

000323 

18 000324 

19 000330 
000330 
000332 

20 000334 
000334 

000340 

21 000342 
000342 
000344 

22 000346 
23 

24 000350 

25 000352 

26 000354 



28 000360 

29 

30 000362 

31 

32 000366 
000366 
000370 

33 000372 

34 000374 
000374 
000376 

35 000400 
36 

37 000402 
000402 

000406 

38 000410 
39 

40 000412 
000412 

000416 

41 000420 

42 000424 



3 000426 

4 000432 

5 000436 

6 000442 

7 000444 

8 000450 

9 000452 



012704 
001160' 
004767 
000240 

004767 
000170 
000730 



012700 

001550' 

104351 

004767 

000020 

010100 
104351 

012700 

001571' 

104351 

010400 
104351 
000207 

010200 
000300 
062700 
173001 

100375 

062700 
035057 



104341 
103776 
000300 

104341 
103776 
000207 



012700 
001462' 
104351 
000403 



012700 

001521' 

104351 

004767 

177724 

000707 



012704 

001120' 

011367 

000520 

052713 

010100 

005724 

042713 

007400 

012405 

050513 



MOV 


*ENDTBLiR4 


CALL 


TERMID 


CALL 


RSET 


FR 


3« 



LOGLUN! .PRINT tATMSG 

MOy *ATHSG.XO 



EMT 


-D351 




CALL 


PRNLUN 




.PRINT 


Rl 




MOV 


RlfXO 




EMT 


-0351 




.PRINT 


♦TINIT 




MOV 


♦TINIT, 


• y.o 



EMT "0351 
.PRINT R4 
MOV R4fX0 



EMT 
RETURN 

PRNLUN: MOV 
SUAB 



-0351 



R2iR0 
RO 



(Don't know speed... 

»Tr« to fiaure out 

jthe terminal ID 
I Set new status. . . 

iHersle. . . 

(Print 1st F»srt of loa 

iPrint LUN. . . 

(...then terminal ID... 

i , , , and finally. . . 
r . . . . the baud rate 



(Copy LUN into RO 
fPut it in hiah byte 



7t! 



ADD 

BPL 
ADD 



#<-10.*400>+l »R0 (Divide by 10 with 

(repeated subtracts 
7t (Q = Q-10f R = R-H till 

(overflow (V set) 
t '0*400+ '0 + <10.* 4 00-1 >>R0 (Correct 



MTERRl ; 



.TTYOUT 

EMT "0341 

DCS .-2. 

SWAB RO 

.TTYOUT 

EMT "0341 

BCS .-2. 

RETURN 

.PRINT »MSG1 

MOV #MSGlrZO 



EMT 
BR 



"0351 
8« 



MTERR2: .PRINT *MSG2 

MOV *MSG2jX0 



8«: 



EMT 
CALL 



BR 



"0351 
PRNLUN 



4t 



(Q 4 R then ASCIIfy. 
(Print 0. . . 



(R to low byte. . 
(Print it . . . 



(Lod attatch error 

( Mersie 

(LoS set status error 

(Include LUN 
(Try next LUN 



.SBTTL Main terminal setup subroutine 

TSETUP! MOV ♦SPTABL-2fR4 (R4 => Baud rate table 

MOV eR3»MSTAT (Save old status... 

BIS ♦^TTSPCtlTCBITt.^fSRS (Set special bits 



io«r 



TST 
BIC 



MOV 
BIS 



(R4) + 
#MSPEEDreR3 



(R4)+fR5 
R5jeR3 



(R4 => Next table entry 
(Clear baud rate mask 

(R5 = Baud from table 
(Set it in CONFGl 
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10 


000454 


022704 
001160' 


CMP 


*ENDTBLfR4 


11 


000460 


001430 


BEQ 


14* 


12 


000462 


012767 
000032 
000410 


MOV 


*32rL0TIM 


13 


000470 


000305 


SUAB 


R5 


14 


000472 


160567 
000402 


SUB 


R5»L0TIM 


15 










16 


000476 


004767 
000046 


CALL 


TERM IB 


17 


000502 


103757 


BCS 


10* 


18 


000504 


042713 RSET; 
010100 


BIC 


*<TTSPC*!TCBIT*> 


19 
20 
21 
22 
23 


000510 


042113 


BIC 


(Rl)+,eR3 


000512 


052113 


BIS 


(Rl)+fBR3 


000514 


011404 12*! 


Moy 


eR4fR4 


24 


000516 


13»! 


•HTSET 


tAREA>R3rR2 




000516 


012700 
001064' 


MOV 


♦AREAiZO 




000522 


012710 
017400 


MOV 


*31.*"0400+0j (0) 




000526 


010360 
000002 


MOV 


R3>2, (0) 




000532 


110260 
000004 


MOVE 


R2f4. (0) 




000536 


104375 


EMT 


"0375 


25 
26 
27 


000540 


000207 


RETURN 




000542 


004767 14»! 


CALL 


6ETSP 






000254 






28 
29 
30 


000546 


000763 


BR 


13* 


000550 


TERMin: 


.MTSET 


*AREA>R3>R2 




000550 


012700 
001064' 


MOV 


♦AREArXO 




000554 


012710 
017400 


MOV 


♦31.*"0400+0»(0) 




000560 


010360 
000002 


MOV 


R3>2. (0) 




000564 


110260 
000004 


MOVB 


R2,4.(0) 




000570 


104375 


EMT 


"0375 


31 


000572 


012705 
001302' 


MOV 


*TTLISTrR5 


32 


000576 


012501 15»! 


MOV 


(R5)+fRl 


33 










34 


000600 


001420 


BEO 


18* 


35 


000602 


004767 
000044 


CALL 


TOUT 


36 


000606 


103773 


BCS 


15* 


37 


000610 


066701 
000246 


ADD 


OUTCT.Rl 


38 


000614 


032701 
000001 


BIT 


♦ liRl 


39 


000620 


001401 


BEQ 


16* 


40 


000622 


005201 


INC 


Rl 


41 


000624 


026721 16»! 
000332 


CMP 


MSGIN><Rl)'f 


42 


000630 


001362 


BNE 


15* 


43 


000632 


026721 
000326 


CMP 


MSGIN+2» (Rl)+ 


44 


000636 


001357 


BNE 


15* 


45 


000640 


000207 


RETURN 




46 










47 


000642 


012701 18*! 
001634' 


MOV 


♦UNKTTrRl 


48 


000646 


000261 


SEC 




49 


000650 


000207 


RETURN 





»Are we thru table? 



i Yes< • «use 3S is 
jMsaic ♦ in .MRKT ara 



SPut rossk in low bate 
FSubtract from insaic * 

(to get * ticks to wait 
fTru to Set terminal ID 

f No dice. . . 

»@R3 fClear special bits 

rTurn off unwanted 

f options 

fTurn on desired options 

fRl => Terminal ID strins 

jR4 => ASCII baud rate 

jStore status 



(Return to caller 

iGet ASCII of baud rate 

fMerae . . . 

rSet new status 



!R5 => List of Terminals 

fRl => Terminal specific 
fcharacter seauence 
JEnd of table - leave ! 
fTru to communicate! • • 

JCarry set = no dice 
fRl => Expected response 

fOdd address? 

fNo. . . 

fVES! Make it even 

fMatch? 

f Nope • . . 
fStill match? 

f Nope. . . 

fReturn with 

fRl => options 

fRl => "Unkown terminal" 

f Set carra. . . 
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3 000652 

4 000656 

5 

6 000662 
000662 

000666 

000672 

000676 

000702 



000710 

7 000712 

8 000714 

9 000720 

10 000724 
000724 

000730 

000734 



000742 
000750 

000756 

11 000760 

12 000764 

13 000766 
000766 

000772 

000776 

001004 
001010 



001016 
14 001020 
15 

16 001022 

17 001026 

18 001030 

19 001034 

20 001036 

21 001040 

22 001044 

23 001046 

24 001050 
25 

26 



112167 
000202 
112167 
000200 



012700 

001064' 

012710 

017403 

010160 

000002 

110260 

000004 

116760 

000154 

000005 

104375 

103442 

105067 

000252 

005067 

000240 

012700 

001064' 

012710 

011000 

012760 

001076' 

000002 

012760 

001052' 

000004 

012760 

000001 

000006 

104375 

105767 

000206 

001775 

012700 

001064' 

012710 

017402 

012760 

001162' 

000002 

110260 

000004 

116760 

000044 

000005 

104375 

000207 

012704 

001122' 

011305 

04270S 

170377 

022405 

001403 

022724 

001612' 

001373 

011404 

000207 



•SBTTL Terminal I/O i Get baud rate routines 

TOUT! MOVB (R1)+.INCNT J6et * char in response 

MOMB (R1)+.0UTCT JGet ♦ char in 'What- 

)are-aou?" seauence 
.HTOUT ♦AREA»Rl.R2fOUTCT fSend Uhat-are-aou? 
MOV tfiiREdtXO 

MOV *31.*"0400+3. F (0) 

MOV R1.2.<0) 

MOVB R2.4.<0) 

MOVB 0UTCTj5.<0) 



19«! 



20* : 



21*: 



22*! 



EMT 
BCS 
CLRB 

CLR 

.MRKT 
MOV 

MOV 

MOV 

MOV 

MOV 

EMT 
TSTB 

BEQ 

.MTIN 

MOV 

MOV 

MOV 



EMT 
RETURN 



GETSP! MOV 



MOV 
BIC 



CMP 
BEQ 
CMP 

BNE 
MOV 
RETURN 



"0375 

20* 

TFLG 

MS6IN+2 



(Output error 
fClear flaS 



pinit input buffer 



*AREAitUAITM>tCRTNEr*l iSet time-out 
tAREA>%0 

tl8,*"0400+0p<0) 

♦UAITMf2. (0) 

♦CRTNE»4. <0) 

*1>6. <0) 



"0375 
TFLG 

19* 

♦AREAi*MSGINfR2»INCNT JGet response. 

*AREA>%0 



♦31.*"0400+2.»<0) 
*MSGrN.2. <0) 



MOVB R2f4.(0) 
MOVB INCNTr5.<0) 



-0375 



♦SPTABL.R4 



r(uith csrra status) 
>R4 => baud rate table 



eR3rR5 JR5 = TCB confiS word 1 

♦"C<MSPEED>fR5 JClear all but baud rate 



(R4)+»R5 

22* 

*UNKSPi(R4)+ 

21* 
eR4»R4 



fcoinpare it with table 
.Branch if eciusl 
.End of table? 

JTru another if not 
>RA => ASCII baud rate 
.Return to caller 



.SBTTL Timeout Completion Routine 
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27 

28 001052 

29 001056 
30 

31 
32 

33 001060 

34 001062 

35 001064 

36 001076 

37 001100 

38 001102 



3 
4 

5 001122 
001124 

6 001126 
001130 

7 001132 
001134 

8 001136 
001140 

9 001142 
001144 

10 001146 
001150 

11 001152 
001154 

12 001156 

13 001160 
14 

15 001162 

16 001172 
17 

18 
19 

20 001173 

21 001206 

22 001220 

23 001232 

24 001244 

25 001256 

26 001270 
27 



105267 
000114 
000207 



000000 
000000 



000000 
000000 



CRTNE: INCB TFLG >Set time-out tlai 

RTS PC tReturn to mainline 

i AraumDnt blocks t workina etorssfe 



007000 

001270' 

003400 

001232' 

002400 

001220' 

006000 

001256' 

005000 

001244' 

002000 

001206' 

001400 

001173' 

000000 

001612' 



000 



INCNT! 
0UTCT5 

area: 
uaitm: 
lotim: 
stat: 

.SBTTL 
t Bsud 
SPTABL! 



.WORD 

.WORD 

.BLK'U 5 

.UORD 

.UORD 

.BLKU 8. 



> Input bute count 
(Output bute count 
rEMT Arduitent block 
iTine-out argument 
) Lo order ticks 
rStstus block <8 words) 



Baud rate mask i ASCII baud rate tables 
rate tiible - in "best auess' order 



mstat: 

ENDTBL! 



HSGINi 
TFLG! 



.WORD 

.UORIi 

.UORD 

.UORD 

.UORD 

.UORD 

.UORD 

.UORD 
.UORD 

.BLKB 
.BYTE 



•NLIST BEX 



061 
061 
063 
061 
062 
064 
071 



B134! 

Biso: 

B300! 

B1200! 

B2400! 

B4800: 

B9600: 



.ASCi:: 

.ASCi;! 

.ASci:: 

.ASCI)! 
.ASCi;! 
.ASCi:! 
.ASCi;! 
.EVEN 



7000rB9600 

3400fB1200 

2400. B300 

6000rB4800 

5000iB2400 

2000. B150 

1400. B134 


UNKSP 

8. 




/134.5 Baud/ 
/ISO Baud/ 
/300 Baud/ 
/1200 Baud/ 
/2400 Baud/ 
/4800 Baud/ 
/9600 Baud/ 



$9600 baud (Scopes 

;1200 baud $LA120 

.300 baud ;LA36 

i4800 baud (Scopes 

(2400 baud (Scopes 

(150 baud (LA36 

(134.5 baud (IBM 

(Oris status 
(End-of-table 
(■=> 'Unknown baud' 
(Response buffer 
(Time-out flaS 



•SBTTL Terminal ID tables 



3 001302 

4 001302 

5 001304 

6 001306 

7 001310 
a 001312 
9 001314 

10 

11 

12 

13 

14 001316 

15 

16 001324 

17 001330 
18 

19 001334 

20 

21 001343 

22 

23 001350 

24 



TTLIST! 



001316' 
001343' 
001367' 
001413' 
001437' 
000000 



.UORD 
.UORD 
.UORD 
.UORD 
.UORD 
. WORD 



VTIOO 

VT52 

LA120 

LA34 

VT55 





(Terminal List. . . 



(Table Stopper 



( DEC terminal command seouences 



004 VTIOO: 



033 
000002 



040 

002 yT52! 
033 



.BYTE 
.EVEN 
.BYTE 
.UORD 



.BYTE 
.EVEN 
.BYTE 



4. 3. ESC. 'C.'c 



(INCNT. OUTCNT.'U-A-Y' sea 



ESC.'C.'?.'l (Response 
NOCRLF.<TAB!BKSP> (Undesi red. Desired 
(options 
.ASCII / VT100/<200> (ASCII terminal ID 



2.2.ESC. 'Z 
ESC. '/.O.O 



(VTS2 response varies 
(u/ model < 
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25 


001354 


000002 




. UORD 


NOCRLFf<TAB!BKSP> 


26 

27 
26 


001360 


040 




.ASCII 


/ VT52 /<200> 


001367 


004 


LA120: 


.BYTE 


4f3FESCr 'C. 'c 


29 








.EVEN 




30 


001374 


033 




.BYTE 


ESC,'C.'?.'2 


31 


001400 


000000 




.UORD 


OiO 


32 


001404 


040 




.ASCII 


/ LA120/<200> 


33 












34 


001413 


004 


LA34! 


.BYTE 


4.3.ESCf 'tf'c 


35 








.EVEN 




36 


001420 


033 




.BYTE 


ESC. 'C.'?.'3 


37 


001424 


000000 




. WORD 


OtO 


38 


001430 


040 




■ASCII 


/ LA34 /<200> 


39 












40 


001437 


002 


VT555 


.BYTE 


2f2.ESC.'Z 


41 








.EVEN 




42 


001444 


033 




.BYTE 


ESC> 'EiOrO 


43 


001450 


000002 




.UORD 


NOCRLF»<TAB!BKSP> 


44 


001454 


040 




.ASCII 


/ VT55 / 


45 








.EVEN 




46 












1 






.SBTTL 


Meessae 


te-At i Initlaliza 



3 






5 


4 








5 


001462 


015 


MSGi: 


6 


001520 


200 




7 


001521 


015 


MSG2: 


8 


001550 


015 


ATMSGJ 


9 


001571 


040 


unit: 


10 


001612 


165 


UNKSP! 


11 


001634 


040 


UNKTT! 


12 


001665 


124 


OFFLIN! 


13 


001715 


000 


CRLF! 


14 








15 






i 


16 








17 


001716 


033 


hello: 


18 


001722 


033 




19 








20 


001724 


033 




21 








22 


001730 


015 




23 


001732 


124 




24 








25 




000000' 


.END 



MesssSe text • . . 

.ASCII <CR><LF>/?C3rinot attach terminal LUH',/ 

.ASCII <200> 

•ASCII <CR><LF>/?St3tu5 error - LUN:/<200> 

.ASCII <CR><LF>/Att3chins LUN;/<200> 

.ASCII / initialized at /<200> 

.ASCIZ /unknown baud rate/ 

.ASCII / unidentifiable teriiiinal/<200> 

.ASCII /Terminal offline - LUN;/<200> 

.ASCIZ // 

Clear screen S sau hello character strinS... 

.ASCII <ESC>"C2J" JVTIOO Erase screen 
.ASCII <ESC>" »VT52 'Exit hold 

; screen mode* 
.ASCII <ESC>"H'<ESC>'J' JVT52 Home + "Erase- 

i to-End-of -Screen ' 

.ASCII <CR><LF> fCRLF (for hardcopu) 
.ASCIZ /TERMINAL INITIALIZED/ 



MTYSET 



»End of program 
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Figure 5-5: Multi-Terminal Eaiample Program (Cont.) 



SYMBOL TABLE 



AREA 


001064R 


LA120 


001367R 


STAT 


001102R 


ATMSG 


001550R 


LA34 


001413R 


S.CTCB= 


000002 


BKSP = 


100000 


LF 


000012 


S.FTC£i= 


000000 


B1200 


001232R 


LOGLUN 


000316R 


S.NTCB= 


000004 


E134 


001173R 


LOTIM 


OOllOOR 


S.STCB= 


000006 


B150 


001206R 


MSGIN 


001162R 


TAB 


000001 


b;moo 


001241R 


MSGl 


001462R 


TCBIT«= 


000100 


B300 


001220R 


MSG2 


001521R 


TERMin 


000550R 


B4800 


001256R 


MSPEED= 


007400 


TFLG 


001172R 


B9600 


001270R 


MSTAT 


001156R 


TINIT 


001571R 


CLUN 


000062R 


MTERRl 


000402R 


TOUT 


000652R 


CR 


000015 


MTERR2 


000412R 


TSETUP 


000426R 


CRLF 


001715R 


MTEXIT 


000250R 


TTLIBT 


001302R 


CRTNE 


001052R 


MTYSET 


OOOOOOR 


TTSPCi= 


010000 


Diyt 


000052R 


M,TSTW= 


000007 


UNKSP 


001612R 


nzii$ = 


010000 


NOCRLF= 


000002 


UNKTT 


001634R 


ENDTBL 


001160R 


OFFLIN 


001665R 


VTIOO 


001316R 


ESC 


000033 


OUTCT 


001062R 


yT52 


001343R 


OETSP 


001022R 


PRNLUN 


000350R 


VT55 


001437R 


HELLO 


001716R 


REMOT»= 


020000 


WAITM 


001076R 


HNGUPt= 


004000 


RSET 


000504R 


...VI = 


000003 


INCNT 


001060R 


SPTABL 


001122R 






. ABS. 


000000 000 
001757 001 








ERRORS 


IlETECTEn; 











VIRTUAL MEMORY USED! 9984 WORDS ( 39 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 5& PAGES 
>V4!MTYSET/L!MEB/L:TTM=V4i MTYSET 
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Chapter 6 

Interrupt Service Routines 



This chapter describes the ways a program can transfer data between 
memory and a peripheral device. First it covers non-interrupt programmed 
I/O; itiext it introduces the concept of using interrupts to handle device I/O 
by comparing the advantages sind disadvantages of in-line interrupt service 
routines and device handlers, i^ifter these general points have been discuss- 
ed, the chapter continues with a description of the structure of an interrupt 
service routine, and shows in detail how to organize and write one. A 
skeleton example of a foreground program that contains an interrupt ser- 
vice routine ends this discussion of applications. The discussion is followed 
by a final section dealing with the considerations involved in using inter- 
rupt service routines in an extended memory environment. 



6.1 Non-lnterrupt Programmed I/O 

One way to move data between memory and a peripheral device is to use 
non-interrupt programmed I/O. According to this method, your program 
operates with the device intenrupts disabled and uses flags to coordinate 
the data transfer. Your program checks the ready bit in the status register 
for a particular device, moves the data when appropriate, and then either 
waits in a tight loop for another ready signal or does other processing and 
polls the device occasionally, li'rogrammed I/O is device-specific and does 
not make use of operating system features designed for I/O processes. In 
addition, it ties up system resources until the I/O transfer is complete. 

However, programmed I/O is sometimes the best method to use. For exam- 
ple, the Resident Monitor uses programmed I/O to print its ?MON-F- 
System halt error message. It first performs a RESET to stop all active I/O. 
Then it waits in a tight loop for the console terminal to print the error 
message, one character at a time. Clearly in such a situation, where the 
monitor itself may be corrupted, no other job or data transfer could be run- 
ning, and the console terminal is the only desirable output device. Also, the 
monitor .PRINT routine may have been corrupted and should not be used. 
Given these requirements, programmed I/O is the best method to use for 
printing this error message. 

In an application program you could use non-interrupt programmed I/O for 
a time-critical device when 1;he program must respond as soon as a 
character becomes available in a register. 
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The following lines of code from RMON demonstrate non-interrupt pro- 
grammed I/O: 



Note that R1 points to the message text. 

TIPS is a word in memory containing the address of 

the terminal printer status register; 

Its ready flag is the high-order bit of the low byte. 

TTPB is a word in memory containing the address of 

the terminal printer buffer. 

Moving a character to the printer buffer resets 

the busy flag in the status register. 



5$: 



TSTB 


@TTPS 


BPL 


5$ 


MOVE 


(R1)+,@TTPB 


BNE 


5$ 



TEST FOR TT BUSY 
IF YES, TEST AGAIN 

IF no; print a character 

BRANCH BACK IF MORE TO PRINT 



The device handler for the single-density diskette, DX, provides another ex- 
ample of programmed I/O. Reading data from the diskette one sector at a 
time, the handler first requests a read of one sector. The diskette completes 
the read operation, places the data in an internal silo, and issues an inter- 
rupt. The handler then disables diskette interrupts and uses programmed 
I/O to move data from the silo into memory. When it is ready to read 
another sector, the handler enables interrupts again. 

The following Unes of code are from the DX handler: 

Note that R4 points to the diskette status register; 

R5 points to the silo; 

R2 points to the data buffer in memory. 

WAIT FOR TRANSFER READY 
BRANCH IFTR NOT UP 
TRANSFER A CHARACTER 
CHECK FOR COUNT DONE 
TRANSFER MORE 

Refer to the PDP-11 Processor Handbook for your computer for more infor- 
mation on non-interrupt programmed I/O. 



TRBYT: 


TSTB 


@R4 




BPL 


TRBYT 


EFBUF: 


MOVB 


@R5,(R2) + 




DEC 


@SP 




BGT 


TRBYT 



6.2 Interrupt-Driven I/O 



Although progranmied I/O is useful in a few situations, generally the best 
way to handle device I/O is through interrupt processing. According to this 
method, a program starts an I/O transfer but continues processing. When 
the transfer completes, the device issues an interrupt. An interrupt service 
routine then determines whether the transfer is incomplete, complete, or 
has encountered an error. It takes the appropriate action (restarting the 
transfer, returning to the program, or possibly retrying the transfer in case 
of error). The advantages of using interrupt-driven I/O are that it enables 
two or more processes to run concurrently and it does not monopoUze 
system resources. 
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6.2.1 How an Interrupt Works ( 

An interrupt is a forced transfer of program execution that occurs because 
of some external event, such as the completion of an I/O transfer. The state 
of the processor prior to the interrupt is saved on the stack so that process- 
ing can continue smoothly after the return from the interrupt. The proc- 
essor saves the Processor Status word, or PS, which reflects the current 
machine state, and the Program Counter, or PC, which indicates the return 
address. 

Next, the processor loads new contents for the PS and PC from two 
preassigned locations in low memory, called an interrupt vector. These 
words contain the address of the interrupt service routine and the new PS, 
which indicates the new pro<;essor priority. When the interrupt service 
routine completes, it executes an RTI instruction, which restores the old PS 
and PC from the stack, and execution resumes at the interrupted point in 
the original program. 



6.2.2 Device and Processor Priorities 

Interrupt processing is closely related to device and processor priorities. 
Figure 6-1 illustrates the RT-11 priority structure. Each device on the 
system has a priority assigned to it and devices that must be serviced as 
soon as possible after they interrupt have the highest priority. DECtape, 
for example, has priority 6; diisks typically have priority 5; terminals and 
other character-oriented devices usually have priority 4. This priority 
system has been carefully designed and in general is adjustable through a 
pluggable priority selector on «}ach I/O device interface. You can control the 
ordering of devices with the same priority. For these devices, the one 
closest to the CPU on the bus is serviced before other devices when inter- 
rupts occur simultaneously. 

Figure 6-1: RT-11 Priority Structure 

PROCESSOR PRIORITY SOFTWARE PRIORITY 

7 "^ DEVICE HANDLERS 

AND 

5 f INTERRUPT SERVICE ROUTINES 

4 




FORK LEVEL 



_^ FOREGROUND COMPLETION ROUTINES 
"^ FOREGROUND MAINLINE 

^ BACKGROUND COMPLETION ROUTINES 
\ BACKGROUND MAINLINE 



MONITOR'S IDLE LOOP 



The central processor operates at any one of eight levels of priority, from 
to 7. (The LSI processor is an exception; it operates at either or 7.) When 
the CPU is operating at priority 7, no device can interrupt it with a request 
for service. When the CPU is operating at a lower priority, only a device 
with a higher priority can cause an interrupt. You can adjust the 
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processor's priority from within an interrupt service routine by modifying 
the Processor Status word. In an RT-11 system, software tools are provid- 
ed to do this for you, so you never directly modify the PS yourself. The tools 
include the .MTPS and .MFPS programmed requests, and the .INTEN and 
.FORK macros. 

The interrupt system allows the processor to continually compare its own 
priority with that of any interrupting devices and to acknowledge the 
device with the highest level above the processor's. This system can be 
nested — that is, the servicing of one interrupt can be left in order to service 
an interrupt with a higher priority. Service continues for the lower priority 
device when the higher priority device is finished. 

See the PDP-11 Processor Handbook for your computer for more informa- 
tion on priorities and interrupts. See also the Peripherals Handbook, the 
Microcomputer Handbook, the Terminals and Communications Handbook 
and the Memories and Peripherals Handbook. 

6.2.3 Processor Status (PS) Word 

The Processor Status (PS) word occupies the highest address on the I/O 
page. (Again, the LSI processor is an exception; its PS is not addressable on 
the I/O page. The monitor refers to the PS by using the MTPS and MFPS 
instructions.) It contains information on the current status of the machine. 
This information includes the current processor priority, current and 
previous operational modes, the condition codes describing the results of 
the last instruction, and an indicator to cause the execution of an instruc- 
tion to be trapped (used for program debugging). 

Figure 6-2 illustrates the bits in the PS. Bits 5 through 7 determine the cur- 
rent processor priority. (In an LSI system, only bit 7 determines the priori- 
ty; priority is either or 7.) By changing bits, you alter the CPU's priority. 
You can change the priority to 7, for example, to prevent any more inter- 
rupts from occurring. When you are servicing a particular interrupt, you 
can change the processor priority to the priority of that device so that only 
devices with a higher priority will interrupt that service routine. (Specific- 
ally, the device you are servicing cannot interrupt.) In general, you need not 
access the PS yourself; use the macros provided in RT-11, such as .INTEN 
and .FORK, to change the processor priority. 

6.3 In-Line Interrupt Service Routines Versus Device IHandlers 

Because both non-interrupt programmed I/O and interrupt-driven I/O are 
valid processes in an RT-11 system, when you need to interface a new 
device to your system — one that is not already supported by RT-11 ~ 
your first decision must be whether to use in-line interrupt service or to 
write a device handler for it. Whatever your decision, both interrupt service 
routines and device handlers can include non-interrupt programmed I/O 
sections as well as interrupt-driven code. The normal RT-11 interface be- 
tween the monitor and a peripheral device is a device handler, which exists 
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Figure 6-2: Processor Status (PS) Word 
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as a memory image file on a mass storage device, and resides in memory 
when it is needed to perform device I/O (see Chapter 2). A device handler 
usually includes an interrupt siervice routine within it. 

If you choose to use an interrupt service routine, you must place the routine 
within your program so that your program directly changes the status and 
buf f<jr registers for a specific d<3vice, and it can service the interrupts within 
its own code. This means, of c:ourse, that the interrupt service code must 
always be resident in memory. 

On the other hand, if you choose to use a device handler, the interrupt ser- 
vice code is contained within t;he handler, not in your program. You issue 
.READ and .WRITE programmed requests from your main program, and 
the monitor and the handler toigether initiate the data transfer, service the 
interrupts, and notify your program when the transaction is done. In an SJ 
system, or for a background job in FB, the handler must be resident only 
when your program actually needs it to perform I/O. (That is, the handler 
must be resident whenever a file or channel is open.) For foreground jobs 
and system jobs in an FB or XM system, you must load the handler (by us- 
ing the monitor LOAD command) before you execute your program, so that 
the handler is always resident. 

How you decide which method is more suitable for your new device depends 
largely on how you want the device to appear to system and application pro- 
grams. In general, you should use in-line interrupt service for sensor or con- 
trol devices, such as analog-to-digital converters. You should service 
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devices that appear to be block-replaceable, file-structured mass storage 
devices, such as disks and diskettes, through device handlers. You can ser- 
vice most communications hardware by either method; the decision rests on 
other criteria. 

The two major advantages of in-line interrupt service routines are their 
speed and the amount of control information they provide. Because there is 
no monitor overhead involved in a data transfer, an in-line routine can often 
handle interrupts faster than a device handler can. If the speed of servicing 
interrupts is crucial to your appUcation, you may choose to write an in-line 
interrupt service routine even if the device is a disk. 

An in-line routine has access to all the device control and status registers 
for a device, as well as its data buffer registers. (Of course, a device handler 
has access to all the same registers, but the program using the handler does 
not.) It can pass a lot of information to the program. This provides a great 
deal of flexibility in the way the program calls the interrupt service routine, 
and in the amount of information the routine returns to it. 

The three major advantages of using device handlers are that they provide 
device independence for your programs, they can share processor time with 
other processes, and they are simple to use. Device handlers have a stan- 
dard protocol for interfacing to the RT-11 monitor. There is also a standard 
protocol for the interface between the monitor and a program, so that any 
program that conforms to the monitor standards can use the handler. This 
includes application programs, system utility programs, and RT-11 
language processors such as MACRO-11, FORTRAN IV, and BASIC-11. 
Thus, the device handler makes a new device available to a large number of 
programs without any special modification. (In addition, a device handler 
for a random-access device makes the RT-11 file system available on the 
device at no extra cost.) In contrast, an in-line interrupt service routine 
makes the new device available to just one appUcation program. 

Device handlers are easy to use. Because they are the standard RT-11 
means of handling device I/O, the procedure for writing them and using 
them is clear and straightforward. This procedure is simplified further by 
the fact that RT-11 provides macros to write a handler; there are also 
keyboard monitor commands that install handlers into the monitor device 
tables and load them into memory. In addition, a device handler permits 
you to take advantage of the monitor programmed requests for performing 
data transfers. Finally, a device handler is the only way you can interface a 
device to a virtual job in an XM system. 

Figure 6-3 highlights some differences between in-line interrupt service 
routines and device handlers. 

If you decide that your new device requires an in-line interrupt service 
routine, read the rest of this chapter to learn how to plan and write one. If 
you decide that a device handler is more suitable, read the rest of this 
chapter and then go on to Chapter 7 to learn how to plan, write, and debug a 
handler. 
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Figure 6-3: In-Line Interrupt Service Routines and Device Handlers 
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6.4 How to Plan an Interrupt Service Routine 

The most important part of writing an in-line interrupt service routine is 
taking the time to plan carefully. Follow these guidelines: 

Get to know your device 

Study the structure of an interrupt service routine 

Study the skeleton interrupt service routine 

Think about the requirements of your program 

Prepare a flowchart of your program 

Write the code 

Test and debug the program 

6.4.1 Get to Know Your Device 

Getting to know your new device is crucial to writing an interrupt service 
routine that works correctly. If your device is a DIGITAL peripheral, con- 
sult the hardware reference manual for that device. You can also learn a lot 
from the PDP-11 Peripherals Handbook. If your device is not from 
DIGITAL, study the documentation for it carefully. Regardless of the for- 
mat of the documentation (whether it is a manual, a brochure, or a set of 
engineering prints), it should contain the vital information you need to sup- 
port it on a PDP-11 system. Be sure you obtain this information. 

In any case, you must understand how the device operates: what it needs 
from you, and how it handles data transfers. Use the following checklist to 
make sure you have enough device-specific information to write the service 
routine. Do not attempt to write any code until you have considered each 
question. 

Some of the following questions do not apply to all types of devices. Some 
are for mass storage devices, some are more appropriate for sensor devices 
or communications devices. Consider each question carefully, though, to see 
if it applies to your device. 

• What is the interrupt vector (or vectors) for the device? 
Decide what the interrupt vector should be. Consider both conflicts 
with existing RT-11-supported devices and also conflicts with devices 
supported by other PDP-11 operating systems, if you use those 
systems. Once you decide on the vector, make sure the device is install- 
ed properly and that the hardware is jumpered to that address. RT-11 
requires all vectors to be below location 500 and some low-memory 
locations are not available for use as vectors. Chapter 2 lists the cur- 
rent PDP-11 vector assignments. 

• What are the control and status registers? 
Leani where these registers are located and what the bits in each mean. 
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• 



• 



What is the priority for the device? 

Is the device DMA (Direct; Memory Access) or programmed transfer 
(word- or character-oriented)? 

What are the data buffer registers? 

Iiearn where these registersi are located and what the bits in each mean. 

What are the op codes for typical operations? 

l-earn how to initiate the various operations by manipulating the bits 
in the device registers. Device handlers tend to perform read, write, 
seek, and reset operations. 

W^hen does the device interrupt? 

Some devices interrupt for each character; others are word-oriented, 
block-oriented, or packet-oriented. Some devices interrupt twice for 
certain operations, such as seek or drive reset. Find out if your device 
does this, and plan now to take this information into account later. 

What is the basic unit for data transfers? 

This relates to the previous question, of course, but you must deter- 
mine whether to send I/O requests to the device as byte, word, or block 
counts. If, for example, your program deals in terms of words and the 
device is character-oriented, you may have to convert the word count 
to a byte count in the service routine. 

Does the device want a positive or negative byte count? 

Some devices require a negative byte or word count. If your device is 
one of those, you may need to negate the count in the service routine. 

What is the device structure, or geometry? 

If the device is a disk, find out how the cylinders, tracks, and sectors 
are structured. Determine their size. Find out if the device requires in- 
terleaving, and, if so, learn, how to optimize for speed. (Interleaving 
describes the process for ^iriting data to a spinning device that re- 
quires program intervention between sectors. The disk is constantly 
moving; data is written into one sector, the program intervenes as the 
adjacent sector spins past, then more data is written into the next 
available sector.) 

What is the buffering arrangement? 

Some devices transfer data to your program one character at a time. 
Others buffer data internally in a silo, or send it in packets. Decide how 
to buffer the data in your program. Make sure the buffer space you 
allocate is leirge enough. 

How do you calculate the address of the data on the device? 
This relates to the device's structure. Study the device now and deter- 
mine how to find the data you want on it. Note that RT-11 block 
numbers must be converted to device-specific addresses. Note also 
that some processors have no multiply or divide instructions. 
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• What "housekeeping" operations does the device require? 

Some devices require a drive reset before a retry. Others require that 
the device be selected or that a disk pack be acknowledged before you 
can perform any operations on it. You must do a drive reset after a seek 
incomplete or a drive error, for example. 

• How will you handle errors and exception conditions? 

First you must decide which errors are hard and will abort the transfer, 
and which errors are soft and will retry the transfer. Some typical soft 
errors include checksum errors, data late errors, and timing errors. 
Decide how many times you will retry the transfer for soft errors, and 
how you will handle a hard error condition. 

• What are the abort considerations? 

Consider whether the device is relatively fast or slow. Keep in mind 
that you do not want to issue a controller reset if only one unit of a two- 
unit controller is affected by a program's abort because this can in- 
terfere with the operation of the second unit. Similar considerations 
may apply to dual-ported devices. 

6.4.2 Study the Structure of an Interrupt Service Routine 

Section 6.5 describes the structure of an interrupt service routine. Read this 
section carefully. Appendix C contains a sample application program that 
does in-Une interrupt service. Read that program, too, and study its 
structure. 

6.4.3 Study thie Siceleton Interrupt Service Routine 

Section 6.6 contains a skeleton outUne of a foreground job with an in-Une in- 
terrupt service routine. Study this outline to be sure you understand the 
flow of execution. 

6.4.4 Think About the Requirements of Your Program 

Remember that the interrupt service routine is part of your program and 
decide where to place it in the program. Review the material in Chapter 2 on 
swapping the USR. If you plan to execute your program in an XM system, 
read Section 6.7 for XM considerations. 

6.4.5 Prepare a Flowchart of Your Program 

Many experienced programmers prepare flowcharts after all their programs 
are written, or they omit them entirely. However, flowcharting a system 
with the complexities of interrupt service can help you find loose ends and 
point out errors in your logic. Flowcharts are not much help, unfortunately, 
in pointing out potential race conditions. (A race condition is a situation in 
which two or more processes attempt to modify the same data structure at 
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the same time; as a result, the data structure is corrupted and the integrity 
of the processes is compromise(i. It may be caused by a device interrupting 
while its interrupt service routine is running, due to improper processor 
priority.) When you design your program, examine every step carefully; 
keep in mind what would happen if an interrupt occurred at each instruc- 
tion. This kind of planning can help you avoid race conditions later. 

6.4.6 Write the Code 

If you have followed the recommended steps so far, writing the code for the 
interrupt service routine itself should be relatively simple. You can borrow 
as much code as possible fromi other interrupt service routines you have 
studied. Start with a general outline, then add details to reflect the specifics 
of your particular device. When you are satisfied with the code, have check- 
ed it thoroughly for logic errors, and it assembles properly, you are ready to 
test and debug it. 

6.4.7 Test and Debug the Program 

The only way to test a program with in-line interrupt service is to try ex- 
ecuting it. If the program is operating correctly, it should be able to read or 
write data accurately, should not lose any data, and should handle error 
conditions properly. Try executing the program in a test situation with data 
you have prepared. If you find errors, link the program with ODT (not VDT) 
and try running it step by step. Make coding corrections, reassemble the 
program, and retry it as necessary. 



6.5 Structure of an Interrupt Service Routine 

The following sections outline the general structure of an in-line interrupt 
service routine. Read them carefully and determine which items apply to 
your own situation. 

6.5.1 Protecting Vectors: .PROTECT 

In FB or XM systems where more than one job can be running, you should 
use the .PROTECT programmed request to protect an interrupt vector 
before you move a value to it. This process makes sure that the vector does 
not already belong to the monitor or to another job. It gives ownership of 
the vector to your job, and protects it from interference from another job or 
the monitor by setting bits in the monitor bitmap. (Chapter 3 describes the 
low-memory bitmap in detail.) Your job should abort immediately if the 
.PROTECT request fails; your job must not access a vector that is already 
in use. See Sections 6.5.2. and 6.6 for examples of how to use .PROTECT. 

See the RT-11 Programmer's Reference Manual for the format of the 
.PROTECT programmed request. 
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Even though the .PROTECT request has no meaning in an SJ system, it is 
advisable to use it in your program. The request takes no action, returning 
immediately to your program, yet using it simplifies conversion later if your 
program needs to run in an FB environment. 



6.5.2 Setting Up the Interrupt Vector 

Your program must take care of moving the address of your interrupt ser- 
vice routine to the first word of the interrupt vector. RT-11 requires all in- 
terrupts to raise the processor priority to 7, so your program must fill in the 
second word of the interrupt vector with 7 as the new priority. The follow- 
ing lines of code show a typical way for a program to set up the two- word in- 
terrupt vector. Note that a program should not set up a vector until the vec- 
tor is protected. For this example, assume the device name is XX, and the 
interrupt vector is at 220 and 222. 

XXVEC = 220 ;DEFINE THE VECTOR 

PR7 = 340 ; PRIORITY 7 = 340 

The entry point for the Interrupt service routine Is ISREP: 



.PROTECT #AREA,#XXVEC 
BCS NOVEC 

MOV #ISREP,@#XXVEC 
MOV #PR7,@#XXVEC + 2 



PROTECT THE VECTOR 
VECTOR IN USE 
SET UP FIRST WORD 
SET UP SECOND WORD 



6.5.3 Stopping Cleanly: .DEVICE 

The .DEVICE programmed request is meaningful only in FB and XM 
systems. Its purpose is to turn off a device (by clearing its interrupt enable 
bit) if its associated program is aborted with CTRL/C, or when the program 
exits. (See the RT-11 Programmer's Reference Manual for the format of the 
.DEVICE programmed request. See Section 6.6 of this manual for an exam- 
ple using .DEVICE.) 

This request is not required in an SJ environment. However, even though 
the request has no meaning in an SJ system, it is advisable to use it in your 
program. The request takes no action, returning immediately to your pro- 
gram, yet using it simplifies conversion later if your program needs to run 
in an FB environment. 

When a program in SJ exits, the monitor waits for all I/O to finish if there is 
an active queue element outstanding. In FB, when a program exits, the 
monitor not only waits if there is an active queue element outstanding, but 
in addition, it enters the device handler at its abort entry point. If a job is 
aborted with CTRL/C, or if it issues a .HRESET request, the SJ monitor ex- 
ecutes a hardware reset to stop I/O on all devices. If you are designing the 
hardware for your device, make sure that it stops cleanly when it receives 
the bus-initialize signal. 
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6.5.4 Lowering Processor Priority: .INTEN 

When an interrupt occurs, control passes to your interrupt service routine 
entry point, the address you supplied as the first word of the interrupt vec- 
tor. At this point, the processor priority is 7, and all other interrupts are 
prohibited. If you need to do anything with all interrupts disabled, this is 
where the code belongs. It should be as short and efficient as possible and 
should not destroy the contents of any registers. If this code needs to use 
registers, it must save them and restore them before issuing the .INTEN 
call. If the code executed at priority 7 is too long, system interrupt latency 
(a measure of how quickly the system can respond to an interrupt) will suf- 
fer. A good guideline is to spend no more than 50 microseconds at priority 7. 

You should lower the processor priority to that of the device as soon as 
possible. This means that only devices with a higher priority than this one 
will be able to interrupt its service routine. To lower the priority, use the 
.INTEN programmed request. The stack pointer and general registers RO 
through R5 must contain the same values when your interrupt service 
routine issues the .INTEN request as they did at the interrupt entry point. 
If your interrupt service routine is not written in Position-Independent 
Code (PIC), use the following format: 

.INTEN prio 

The .INTEN call generates the following code: 

JSR R5,@54 

.WORD -C < PRIOM0> &340 

If your interrupt service routine} is written in PIC, use the .INTEN call with 
a second argument, PIC. (The argument can actually be anything at all, as 
long as it is not blank.) 

.INTEN prio.PIC 
The second format generates Position-Independent Code: 

MOV @#54,-{SP) 

JSR R5,@(SP) + 

.WORD -C<PRIO''40>&340 

Both formats cause a jump to the monitor's INTEN routine, which lowers 
the processor priority, and, in FB and XM, switches to system state. The 
monitor then calls the interrupt service routine back as a co-routine. R4 and 
R5 are available for use on return from the call. You must not destroy the 
contents of any other registers. If you need RO through R3, save them on 
the stack or in memory and restore them before you exit. If you need to 
preserve values across the .INTEN request, you must save them in memory 
before the call and restore them after it. Likewise, if the contents of the PS 
are important, such as the values of the condition bits, you should save 
them before issuing the .INTEN call. Since .INTEN causes a switch to the 
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system stack in FB and XM, you should avoid using the stack excessively 
once you are in your interrupt service routine. Save and restore registers 
and the PS, as necessary, by using memory locations instead of the stack. 

NOTE 

Saving values in memory locations may prevent your inter- 
rupt routine from being re-entrant. If you intend to use the 
routine for multiple devices, be careful about re-entrancy 
when you design it. 

(See the RT-11 Programmer's Reference Manual for more information on 
.INTEN. See Section 6.6 of this chapter for an example using .INTEN. See 
Section 6.5.7 for a summary of the interrupt service routine macro calls.) 



6.5.5 Issuing Programmed Requests: .SYNCH 

The .SYNCH call is useful mainly in the FB and XM environments. Its pur- 
pose is to make sure that the correct job is running when an interrupt ser- 
vice routine executes a programmed request. Even though the .SYNCH call 
has no meaning in an SJ system, it is advisable to use it in your program. 
The request t£ikes no action, returning immediately to your program, yet 
using it simplifies conversion later if your program needs to run in an FB 
environment. (For the complete expansion of this macro, see the listing of 
the system macro library in the RT-11 Programmer's Reference Manual.) 
See the RT-11 Programmer's Reference Manual for the format of the 
.SYNCH request. 

If you need to issue one or more RT-11 programmed requests from the in- 
terrupt service routine, you must first issue the .SYNCH call. Remember 
that the .INTEN call switched execution to system state, and programmed 
requests can only be made in user state. The .SYNCH call itself handles the 
switch back to user state. Note that you should never issue programmed re- 
quests requiring the USR from within an interrupt service routine, even 
after using .SYNCH. You can also issue .SYNCH after .FORK, which is 
covered in Section 6.5.6. When you issue the .SYNCH call, RO through R3 
and the stack pointer must contain the same values as they did when the 
.INTEN request returned to you. 

Table 6-1 illustrates the format of the synch block, which acts like a com- 
pletion queue element. The information in the seven-word synch block is 
placed at the head of the appropriate job's completion queue. Therefore, the 
code following the .SYNCH request executes as a completion routine, in 
user state, at priority 0. Because of this, your program must either disable 
interrupts before the .SYNCH call, or it must be prepared for the device to 
interrupt again before the .SYNCH code executes. The synch block is 
available for reuse when Q.COMP (offset 14 octal) is 0. You can test the 
synch block easily by issuing another .SYNCH. If control passes to the er- 
ror return (the word following the .SYNCH call), the block is still in use. 
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Tabk 6-1: 


Synch Block 








Offset 


Name 


Agent 




Contents 





Q.LINK 







Reserved 


2 


Q.CSW 


user 




Job number 


4 


Q.BLKN 







Reserved 


6 


Q.FUNC 







Reserved 


10 


Q.BUFF 


user 


RO argument to pass 


12 


Q.WCNT 


monitor 




-1 


14 


Q.COMP 


user 


Assemble a value of here; the 
monitor then maintains the contents 
of this word 



In general, a long time can elapse between the .SYNCH call and the return. 
First, the monitor switches to user state, and a scheduling pass is required 
to d(Jtermine whether or not a context switch is also necessary. Then a 
background completion routine may have to wait for a compute-bound 
foreground job to become blocb;ed. So, it may take a considerable amount of 
time before the code following the .SYNCH actually executes. 

In the code following the .SYNCH call, RO and Rl are free for use, as they 
are in any completion routine. However, you must preserve R2 through R5 
if your .SYNCH routine uses <;hem. This poses a problem for R4 and R5, 
whiclli are not preserved across the call. If their contents are important, 
save them in memory before the .SYNCH call. You can use Q.BUFF in the 
synclti block to pass a value into RO for the synch routine. 

The .SYNCH call has an unusual error return. The first word after .SYNCH 
is the return address on error; 1:he second word after .SYNCH is the return 
on success. See Section 6.6 for im example using .SYNCH. See Section 6.5.7 
for a summary of the interrupt; service routine macro calls. 

In the SJ environment, routines following .SYNCH calls (and, in fact, com- 
pletion routines in general) are nested (that is, they can interrupt each 
other). They are seriaUzed in FB and XM. In SJ, the .SYNCH mechanism 
simulates the FB and XM sch(}me but does not duplicate it. 

6.5.6 Running at Fork Level: .FORK 

The .FORK programmed requfjst gives you another way to lower the pro- 
cessor priority. (See the RT-11 Programmer's Reference Manual for the for- 
mat of the .FORK programmed request. For the complete expansion of this 
macro, see the hsting of the system macro library in that manual.) 

When you issue a .FORK call, the fork block is added to a fork queue, which 
is a first-in, first-out list. Fork routines (all the code following a .FORK call) 
execute in system state at priority 0, after all interrupts have been serviced, 
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but before the monitor switches to user state. Context switching is in- 
hibited as well during the time fork routines are executing. (See Figure 6-1 
for a review of RT-11 priority levels.) 

R4 and R5 are preserved across the .FORK call. In addition, RO through R3 
are free for use after the call. Like .SYNCH, the .FORK call assumes you 
have not changed RO through R3 or the stack since the .INTEN call return- 
ed to you. See Section 6.5.7 for a summary of the interrupt service routine 
macro calls. Note that you cannot issue .FORK without a prior .INTEN 
call. 

You must provide a four-word block of memory for the fork queue element, 
the last three words of which will contain R4, R5, and the return PC. The 
first word is a link word, which must be when you issue the .FORK re- 
quest. Because a .FORK routine should not be re-entrant, make sure that 
the device cannot interrupt between the time you issue the .FORK call and 
the time the .FORK routine (the code following the call) begins to execute. 

You may not re-use a fork block until the fork routine has been entered. It is 
safe to assume that the fork block is free when the call that used it returns. 
See Table 6-2 for an illustration of the fork block. 



Table 6-2: 


Fork Block 






Offset 


Name 


Agent 


Contents 







F.BLNK 


monitor 


Link word 


2 




F.BADR 


monitor 


FORK routine address 


4 




F.BR5 


monitor 


R5 save area 


6 




F.BR4 


monitor 


R4 save area 



Generally, .FORK is used in device handlers. To use it in an interrupt ser- 
vice routine, you must first set up a pointer, called $FKPTR. The recom- 
mended way to do this in a main program is as follows: 



MOV 
ADD 
MOV 



$FKPTR: 
XXFBLK: 



@#54,R4 

402(R4),R4 

R4,$FKPTR 



WORD 
WORD 0,0,0,0 



Then, in the interrupt service routine, you can use the normal form of the 
.FORK macro: 



.FORK 



XXFBLK 



The .FORK macro expands as follows: 



JSR 
.WORD 



R5,@$FKPTR 
XXFBLK-. 
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In aB SJ system, there is no real support for .FORK unless you select timer 
support as a special feature at system generation time. Instead, the monitor 
simulates the process by saving registers RO through R3 before calling the 
interrupt service routine back. Beyond that, it does not attempt to serialize 
fork routines. Note that in your interrupt service routine, no registers are 
free for use before the .INTEN call. After the .INTEN, you can safely use 
R4 and R5. See Section 6.5.7 for a summary of the interrupt service routine 
macro calls. 

The .FORK request has several applications in a real-time environment 
because it permits lengthy lint noncritical interrupt processing to be 
postponed until all other interi-upts are dismissed. 

For example, the CRll card reader handler internally buffers 80 columns of 
data. It receives an interrupt once per column, and translates and moves 
the character into its internal b>uffer at interrupt level. It then moves its in- 
ternal buffer to the user buffer, a process that can take up to 2.5 msec. In 
RT-11 Version 2C, this process took place at priority level 6, which meant 
that interrupts at this priority and lower could be locked out for this time. 
This can cause data late errors on communications devices when the card 
reader is active at the same time. 

This problem is not solved by simply dropping priority to 0, since the card 
reader could have interrupted a lower-priority device. Lowering priority 
causes problems in the other device handlers that are re-entrant. Using a 
.SYNCH does not always solve the problem, either, since the SJ monitor on- 
ly simulates a .SYNCH and dirops priority to 0, which produces the same 
problems for re-entrant handlers. The FB monitor must perform a context 
switch since .SYNCH returns to the caller in user context, running on the 
user stack. The context switch is a lengthy process and does not occur at all 
if there is a compute-bound foreground job. 

The .FORK request is the solution to the problem. It returns at priority 0, 
but only when all other interrupts have been dismissed and before control is 
returned to the interrupted user program. (Note that you dismiss an inter- 
rupt when you leave interrupt level, by any one of several means.) 



6.5.7 Summary of .INTEN, .FORK, and .SYNCH Action 

Table 6-3 summarizes the efl:ects of the .INTEN, .FORK, and .SYNCH 
macro calls. Figure 6-4 describes the status of the registers for each call. 

Table 6-3: Summary of Interiupt Service Routine Macro Calls 

Macro New Now Registers Available Your Data Preserved 

Call Priority Stack to Use After Call Across Call In 



.INTEN 


device's 


System 


R4, R5 


none 


.FORK 





System 


R0-R5 


R4, R5 


.SYNCH 





User 


RO, Rl 


RO 



Interrupt Service Routines 6-17 



Figure 6-4: Summary of Registers in Interrupt Service Routine Macro 
Calls 



OPERATION 



RO R1 R2 R3 R4 R5 



. CONTENTS UNKNOWN , 



INTERRUPT 



. INTEN 



.FORK 



.SYNCH 



,, li M 



•SAVE/RESTORE IF NEEDED • 



i 



FREE TO USE ■ 



■SAVE/RESTORE 



'I J •[ •' 



FREE TO USE 



I I t i 



-FREE 1 \- 



■ SAVE/RESTORE 



I I I I I I 



(LOADED 
WITH YOUR 
DATA) 



(CONTAINS 
YOUR DATA) 



6.5.8 Exiting from interrupt Service: RTS PC 

The .INTEN request causes the monitor to call your interrupt service 
routine as a co-routine. At the end of your routine, when it is time to exit, 
use an RTS PC instruction. This returns control to the monitor, which 
restores R4 and R5 and then executes an RTI instruction. 

You also exit from .FORK and .SYNCH routines with an RTS PC instruc- 
tion. Be sure that the stack is the same as it was upon entry, and that any 
registers that must be preserved have their original contents. 



6.5.9 Servicing Interrupts in FORTRAN: iNTSET 

The INTSET function is available in RT-11 to establish a FORTRAN 
subroutine that will be initiated via interrupt and that will run at interrupt 
level. See the SYSLIB routines in the RT-11 Programmer's Reference 
Manual for a more complete description of INTSET. 
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6.6 Skeleton Outline of an Interrupt Service Routine 

Figure 6-5 shows a foreground main program that contains an in-line inter- 
rupt service routine. The foreground program performs some initialization 
tasks and then suspends itself. When data is available from a peripheral 
device the interrupt service routine collects it. When all the data is 
gathered, the interrupt service routine resumes the main program, which 
can then process the new information before suspending itself again. The 
main program's processing cc^uld involve some manipulation of the new 
data or it could be writing the data to a file shared by a background data 
analysis job. Note that because this example forces the job number to 2, it 
cannot execute properly in a system with the system job feature present. 

For this example, xx represents the device name. 



Figure 6-5: Skeleton Interrupt Service Routine 



** MAIN PROGRAM ** 



xxVEC = vvv 

PR7 = 340 

DEVPRI= 5 

xxCSR = nnnnnn 

lENABL = 100 

START: .PROTECT #LIST,#xxVEC 

BCS ERROR 

MOV #ISREP,@#xxVEC 

MOV #PR7,@#xxVEC + 2 

.DEVICE #L1ST,#DEVLST 



THE DEVICE VECTOR 

PRIORITY 7 

DEVICE PRIORITY = 5 

(0-7, NOT 000-340) 

THE DEVICE CONTROL REGISTER 

INTERRUPT ENABLE BIT 

PROTECT THE VECTOR 

HANDLE .PROTECT ERROR 

SET UP FIRST WORD 

OF VECTOR 

SET UP SECOND WORD 

OF VECTOR 

TO DISABLE DEVICE ON 

EXIT OR ABORT 



Lines of code here initialize Input buffers In the service routine; 
initialize other pointers and flags 



SPND: 



BIS 
.SPND 



#IENABL,@#xxCSR 



Lines of code here store the data; 
reset some flags 

BR SPND 

DEVLST:.WORD xxCSR 

.WORD 

WORD 

LIST: .BLKW 3 
ERROR: 



jENABLE INTERRUPTS 

;WAIT UNTIL THERE IS SOME DATA 



;WAIT FOR MORE DATA 
;LIST FOR .DEVICE 



;EMT ARG BLOCK 

;ROUTINES TO HANDLE ERRORS 
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INTERRUPT SERVICE ROUTINE 



ISREP: 



.INTEN DEVPRI 

If there Is more data to collect: 

BR RETURN 

If there Is no more data to collect: 

.SYNCH #SYNBLK 
SYNERR 



BR 
.RSUM 
RETURN: RTS PC 



;THE INTERRUPT ENTRY POINT; 
;PRIORITY IS 7 

NOTE: NOT #DEVPRI. 
LOWER TO DEVICE PRIORITY; 
WE ARE IN SYSTEM STATE 
WITH R4 AND R5 AVAILABLE. 



GO BACK TO MAIN PROGRAM 
TO PROCESS DATA. 
SYNCH RETURNS HERE ON ERROR 
WAKE UP MAIN PROGRAM 
WAIT FOR ANOTHER INTERRUPT 



SYNBLK: .WORD 0,2,0,0,0,-1,0 



SYNERR: 



NOTE: 2 IS THE JOB NUMBER 
FOR THE FOREGROUND JOB. 
PROCESS SYNCH ERROR 



6.7 Interrupt Service Routines in XM Systems 

If you are not planning to execute your program in an XM environment, 
you need not read this section. 

Of the two kinds of jobs in an XM environment, virtual jobs and privileged 
jobs, virtual jobs cannot contain in-Une interrupt service routines (see 
Chapter 4). By the very definition of virtual mapping, virtual jobs cannot 
access the device I/O page. Therefore, they cannot set a device's interrupt 
enable bit or move data to or from a device's data buffer register. 

If a job containing an in-line interrupt service routine must run in the XM 
environment, it must run as a privileged job. Privileged mapping makes the 
low 28K words of memory and the I/O page available to the program and 
permits the program to map portions of the user virtual address space into 
extended physical memory if the program requires it. 

In order to understand the restrictions that the XM environment imposes 
on interrupt service routines, you must understand that when an interrupt 
occurs in XM, its service routine executes with kernel, not user, mapping. 
This means that whether or not the program has mapped some of its virtual 
address space into extended memory, the interrupt service routine executes 
with the default kernel mapping to the low 28K words of memory plus the 
I/O page. It makes, sense, therefore, that the first XM restriction demands 
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that the mapping for your intesrrupt service routine plus any data it uses 
must be identical to kernel meipping at any time that an interrupt could 
occui'. 

Figure 6-6 shows the default Ikernel mapping scheme, which provides ac- 
cess to the low 28K words of memory plus the I/O page. This is also the 
map]}ing scheme for a privileged job when it first begins execution. And, 
this lis the mapping scheme that takes effect whenever an interrupt is ser- 
viced. (The shaded areas in the figure represent memory that the user job 
cannot access.) In Figure 6-6, the interrupt vector at 200 and 202 contains 
the €sntry point, called ISREF*:, of the interrupt service routine, and the 
value 340, which represents the new PS. When an interrupt occurs, the 
systtjm uses kernel mapping to locate the interrupt service routine. In this 
example, it should start at address 120000. Since privileged mapping and 
kernel mapping are identical in this diagram, the interrupt service routine is 
located in physical memory exactly where the kernel mapping points, so it 
can execute correctly. 

Figure 6-6: Kernel and Privileged Mapping 
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Figure 6-7 shows a privileged! job that changes the user virtual address 
mapping. (The shaded areas in the figure represent memory that the user 
job cannot access.) You can sees from the example that the interrupt service 
routine cannot execute correctly when an interrupt occurs because the in- 
terrupt service routine is not located in physical memory where it should be. 
The memory area pointed to by the kernel mapping contains random data 
or instructions. 
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Figure 6-7: Interrupt Service Routine Mapping Error 
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The second restriction for interrupt service routines in XM relates to the 
way the monitor uses Page Address Register (PAR) 1 with kernel mapping. 
PARI controls the mapping for virtual addresses 20000 through 37776. 
When XM is first bootstrapped with kernel mapping, the virtual addresses 
map directly to the same physical addresses. However, the monitor itself 
uses PARI to map to EMT area blocks and to user data buffers. So, 
whenever the system is running, the kernel virtual addresses in the PARI 
range can be mapped just about anywhere in physical memory and you 
have no way of controlling it. You must be sure that your interrupt service 
routine and any data it needs are not located in the virtual address range 
mapped by PARI. Figure 6-8 illustrates this restriction. Valid locations for 
interrupt service routines, assuming that privileged mapping is identical to 
kernel mapping at the time of the interrupt, are marked on the diagram as 
"OK" 

If your interrupt service routine needs a window into memory, it can borrow 
PARI the same way the monitor does. It must save the contents, set the 
value it needs, and restore the original contents before exiting. It can do 
this at .INTEN or fork level, but not at synch level. 

NOTE 

If your system uses the MQ handler to communicate 
among system jobs, all the restrictions for PARI also ap- 
ply to PAR2 — the range of addresses from 40000 through 

57777. 
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Figure 6-8: PARI Restriction for Interrupt Service Routines 
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One linal piece of information is important if you use .SYNCH in your inter- 
rupt service routine. The lines of code following .SYNCH execute almost 
like a completion routine. Completion routines in XM execute with the user 
registers, the user stack, and with user mapping. But, since the code follow- 
ing .SYNCH is still part of an interrupt service routine, it executes with the 
user registers, but with kernel mapping. So, the code following a .SYNCH 
call in XM must observe the same restriction as the main body of the ser- 
vice routine: its mapping must be identical to kernel mapping at any time 
that an interrupt could occur, or any time the completion routine could be 
executing. Of course, it must observe the PARI and PAR2 restrictions as 
well. 
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Chapter 7 
Device Handlers 



To write a device handler, you first need to know what points to consider in 
the planning stage. These pointis are listed and cross-referenced in the first 
sections of this chapter. The points that have not been treated elsewhere in 
this manual are then describ(}d in detail. The structure of a standard 
handler and a skeleton outline of a typical handler are covered here. After 
this, details are given on the optional features available to handlers and 
their implementation. Optional features include internal queuing, SET op- 
tions, device I/O time-out support, special functions, error logging, and 
special services available in XM systems. 

To write a bootstrap for a system device, you first need to know the dif- 
ferences between a standard handler and a system device handler. These 
differences are discussed in several sections before the final sections of the 
chapter, where you will find explained the assembly, installation, testing, 
and debugging procedures for the new handler. 

Be sure to read Chapter 6, Interrupt Service Routines, before you read 
about device handlers. Section 6.3 of that chapter can help you decide 
whetltier you need to write an in-line interrupt service routine or a device 
handler. 

7.1 How to Plan a Device Handler 

The most important part of writing a device handler is taking the time to 
plan the whole process carefully. Follow these guidehnes: 

Get to know your device 

Study the structure of a standard device handler 

Study the skeleton device handler 

Think about using the special features 

Study the sample handlers 

IPrepare a flowchart of the device handler 

Write the code 

Install, test, and debug the handler 

7.1.1 Get to Know Your Device 

Learning about the characteristics of your device and the bus interface is 
crucial to writing a handler that works correctly. Review the material in 
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Section 6.4.1 so that you can answer all the pertinent questions about your 
device before you attempt to write a handler for it. 

7.1.2 Study the Structure of a Standard Device Handler 

Section 7.2 describes the structure of a standard device handler. Read this 
section carefully; your handler must conform to this structure. 

7.1.3 Study the Skeleton Device Handler 

Section 7.3 contains a skeleton outline of a standard device handler. You 
can use this outline as a starting point when you begin to write your own 
handler. 

7.1.4 Think About Using the Special Features 

Sections 7.4 through 7.9 describe the special features available to device 
handlers. Read these sections carefully to determine whether any of the 
features are applicable to your handler. 

7.1.5 Study the Sample Handlers 

Appendix A contains assembly listings of three RT-11 device handlers 
(RK, DX, and PC) with extensive explanatory comments. Study these 
listings until you feel comfortable with the organization of the handlers, 
and you understand how they implement some of the special features. Ob- 
tain listings of handlers for other devices that resemble yours; you may be 
able to use some of the code that is already written. 

7.1.6 Prepare a Flowchart of the Device Handler 

Preparing a flowchart for your handler can help you plan the contents of the 
various sections. Flowcharting can also help you spot loose ends and errors 
in your programming logic. Unfortunately, flowcharts are not much help in 
pointing out potential race conditions. (A race condition is a situation in 
which two or more asynchronous processes attempt to modify the same 
data structure at the same time; as a result, the data structure is corrupted 
and the integrity of the processes is compromised.) Therefore, when you 
design the handler, examine every step carefully and keep in mind what 
would happen if an interrupt occurred at each instruction. This kind of plan- 
ning can help you avoid race conditions later. 

7.1.7 Write the Code 

If you have followed the recommended steps so far, writing the code for the 
device handler should be relatively simple. You must write Position- 
Independent Code (PIC) for the handler. Review the chapter on PIC code in 
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the PDP-11 MACRO-11 Language Reference Manual if you are not filready 
familiar with it. Copy as much code as possible from the commented device 
handlers in Appendix A, or frora other reUable sources. Start with a general 
outline that conforms to the structure presented in Section 7,2 and then add 
details to reflect the specifics of your particular device. When you have 
thoroughly checked the code for logic errors and it assembles properly, you 
are njady to test and debug it. 

7.1.8 Install, Test, and Debug the Handler 

Sections 7.11 and 7.12 show how to install a new device handler and how to 
begin testing and debugging it. 

7.2 Structure of a Device Handler 

An RT-11 device handler consists of the following six sections: 

Preamble 

Header 

I/O initiation 

Interrupt service 

I/O completion 

Handler termination 

Each section is a separate logical unit, containing code for a particular pur- 
pose. Because the RT-11 system macro library provides special macros to 
generate much of the required code for these sections, the actual lines of 
code that you write yourself are not too complex. 

Before you read ahead, take a minute to glance over the sample device 
handlers in Appendix A and get a feel for the overall structure of the 
handlers. 

7.2.1 Preamble Section 

The device handler source file begins with the preamble section, which in- 
cludes an .MCALL directive foir the .DRDEF macro and any other macros 
you need that this chapter does not explicitly mention. The preamble also 
provides definitions for symbols that you will use later. Much of the work in 
the preamble is done by the .DRDEF macro. 

7.2.1 .1 .DRDEF Macro — Use th(; .DRDEF macro near the beginning of your 
device handler. This macro performs most of the work of the preamble sec- 
tion. Its functions are to: 

• Issue .MCALL directives for all handler-related macros 

• Provide default values for the key system conditionals 
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• Invoke the .QELDF macro to define queue element offsets 

• Define bit patterns for device characteristics 

• Define ddDSIZ as the device size in blocks 

• Define dd$COD as the device identification 

• Set up the device status word from information in ddDSlZ and 
dd$COD 

• Provide default values for the device CSR in ddSCSR and vector in 
dd$VEC 

• Make the symbols dd$CSR and dd$VEC global 

dd represents the two-character device name. 

The format of the .DRDEF macro call is as follows: 

.DRDEF name,code,stat,size,csr,vec 

name is a two-character device name, such as RK for the RK05 disk 
handler. 

code is the octal numeric value that uniquely identifies the device. See Sec- 
tion 7.2.1.2. 

Stat is the device status bit pattern. Your value for stat can use the follow- 
ing symbols (described in Section 7.2.1.3): 

FILST$ WONLY$ HNDLR$ 

RONLYS SPECL$ SPFUN$ 

size is the size of the device in 256-word blocks; use a value of if the device 
is not file-structured (see Section 7.2.1.4). 

csr is the default value for the device's control and status register. 

vec is the default value for the device's interrupt vector. 

.MCALL Directive 

The .DRDEF macro issues the .MCALL directive for the following macros: 



DRAST 


.DRBEG 


.DRFIN 


DRBOT 


.DREND 


.DRSET 


DRVTB 


.FORK 


.QELDF 



In addition, if you assemble your handler with the conditional TIM$IT set 
to 1, .DRDEF issues an .MCALL directive for these macros: 

.TIMIO and .CTIMIO 

System Generation Conditionals 

RT-11 source files make extensive use of conditional assembly directives. 
Sections of source code are included or omitted at assembly time, based on 
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the value of conditional symbols. For example, RT-11 uses the conditional 
ERL$G to indicate whether routines for error logging should be assembled. 

If you use conditional symb<}ls in your handler, you should conform to 
RT-11 standard usage by setting the conditional equal to to indicate that 
the feature it represents is not to be included and by setting the conditional 
to 1 to include the feature. (Note that RT-11 uses only the values and 1 to 
indicate absence or presence of a feature.) See the PDP-11 MACRO-U 
Language Reference Manual for information on the conditional assembly 
directives .IF EQ, .IF NE, and so on. 

The .DRDEF macro sets to the system generation conditionals TIM$IT 
(for device time-out), MMG$T (for extended memory support), and ERL$G 
(for error logging), if you do not define them in a prefix file at assembly time. 
In addition, if the symbols have values other than 0, .DRDEF sets them 
tol, 



Queue Element Offsets 

The .DRDEF macro invokes .CJELDF to define queue element offsets sym- 
bolically. The following exeimple shows the queue element offsets 
generated. (See Section 7.9.3 for the queue element in XM systems.) 

Q.LINK =0 (Link to next queue element) 

Q . C S W =2. (Pointer to channel status word) 

Q.BLKN =4. (Physical block number) 

Q . F U N C =6. (Special function code) 

Q.JNUM =7. (Job number) 

Q . U N I T =7. (Device unit number) 

Q.BUFF =^^010 (User buffer address) 

Q.WCNT ='^012 (Word count) 

Q.COMP = ^ 014 (Completion routine code) 

Q.EL.GH =•^016 (Length of queue element) 

Since the handler usually deals with queue element offsets relative to 
Q.BLKN, the .QELDF macro also defines the following symbolic offsets: 



Q$LII^JK 


= -4 


Q$CSW 


= -2 


Q$BLKN 


= 


Q$FUNC 


= 2 


Q$JNUM 


= 3 


Q$UNIT 


= 3 


Q$BUFF 


= 4 


Q$WCNT 


= 6 


Q$COMP 


= 10 



Symbol Definitions 

Use direct assignment statements to define symbols that you will use later 
in the handler. Typically, the definitions include the device registers and 
other useful internal symbols. Some examples from RT-11 device handlers 
idilow. 



Device Handlers 7-5 



To define an internal symbol for line feed (ASCII 12): 
LF = 12 ;ASCII FOR LINE FEED 



To define other device registers: 



RKDS 
RKER 
RKCS 
RKWC 



= RK$CSR 
= RKDS + 2 
= RKDS +4 
= RKDS +6 



IDRIVE STATUS REGISTER 
ERROR REGISTER 
iGONTROL STATUS REGISTER 
;WORD COUNT REGISTER 



The .DRDEF macro defines the following symbols for you: 



HDERR$ = 1 
EOF$ = 20000 



;HARD ERROR BIT IN THE CSW 
;END OF FILE BIT IN THE CSW 



7.2.1.2 Device-Identifier Byte — The low byte of the device status word, the 
device-identifier byte, identifies each device in the system. You specify the 
correct device identifier as the code argument to .DRDEF. The values are 
currently defined in octal as Table 7-1 shows. 



Table 7-1: Device-Identifier Byte Values 

Value Meaning 






RK05 disk 


1 


TCll DECtape 


2 


Reserved 


3 


Line printer 


4 


Console terminal or batch handler 


5 


RL01/RL02 disk 


6 


RX02 diskette 


7 


PC 11 high-speed paper tape reader and punch 


10 


Reserved 


11 


TUlO magtape 


12 


RFll disk 


13 


TAll cassette 


14 


Card reader (CRll.CMll) 


15 


Reserved 


16 


RJS03/RJS04 fixed-head disk 


17 


Reserved 


20 


TJU16 magtape 


21 


RP02/RP03 disk 


22 


RXOl diskette 


23 


RK06/RK07 disk 


24 


Reserved 
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Table 7-1: Device-Identifier Byte Values (Cont.) 

Value Meaning 

25 Null handler 

26-30 Reserved (for DECnet) 

31-33 Reserved (for CTS-300 LQ, LR, LS) 

34 TU58 DECtape 11 

35 TSll magtape 

36 PDT-11/130 

37 PDT-11/150 

40 Reserved 

41 Serial line printer handler (LS) 

42 Internal message pseudo device (MQ) 

44 Down-line load handler (XT) (MRRT-11 only) 



To create device-identifier codes for devices that are not already supported 
by RT-11, start by using code 377 octal for the first device, 376 for the se- 
cond, and so on. This procedure should avoid conflicts with codes that 
RT~11 will use in the future I'or new hardware devices. 

7.2.1.3 Device Status Word — '^Phe device status word identifies each unique 
physical device in an RT-11 siystem and provides other information about 
it, such as whether it is random- or sequential-access. The value of the 
status word is stored in block of the handler file and in the $STAT table 
when the device is installed; i;he .DSTATUS programmed request returns 
this value to a running progi-am. The .DRDEF macro sets up the device 
status word based on the arguments code and stat. 

Table 7-2 shows the meaninj? of the bits in the device status word. The 
.DRDEF macro uses the sy]iibol ddSTS to represent the device status 
word. 

Table 7-2: Device Status Word 

Bit Symbol Meaning 

0-7 Device-identifier byte (see Section 7.2.1.2) 

8-9 Reserved 

10 SPFUN$ = .SPFUN requests are invalid 

1 - Handler accepts .SPFUN requests 

1 1 HNDLR$ = Enter handler at abort entry point only if there is an 

active queue element belonging to the aborted job 
1 - Enter handler at abort entry point on all aborts 

This bit is ignored in SJ systems. 
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13 


WONLY$ 


1 = 


14 


RONLY$ 


1 = 


15 


FILSTS 


= 



Table 7-2: Device Status Word (Cont.) 

Bit Symbol Meaning 



12 SPECL$ 1 = Special directory-structured device {examples are 

MT, CT) 

This is a write-only device 

This is a read-only device 

= This is a sequential-access device (examples are MT, 
CT, PC, LP) 

1 = This is a random-access device (examples are RK, 
DX) 



Note that bit 11 in the status word should be set for device handlers that 
remove the queue element on entry and queue internally, and for devices 
such as magtape that have internal data that could need modification on 
abort. See Section 7.4 for more information on device handlers that do their 
own queuing. See Section 7.8.5 for details on special devices (such as 
magtape). 

All device handlers that have bit 15 set are assumed to be RT-11 file- 
structured devices by most of the system utility programs. 

An easy way to define the device status word is to use the mnemonics for 
the bit patterns that .DRDEF defines for you. Thus, you can create the stat 
argument by ORing together the appropriate symbols from the list below. 



FILST$ ==100000 
RONLY$ = = 40000 
WONLY$ = = 20000 
SPECL$ = = 10000 
HNDLR$ = = 4000 
SPFUNS = = 2000 



FILE STRUCTURED RANDOM ACCESS 

READ ONLY 

WRITE ONLY 

NO DIRECTORY 

ENTER HANDLER ON ABORT 

ACCEPTS SPECIAL FUNCTIONS 



For example, form the stat argument for the RK, MT, and LP handlers as 
follows: 

For RK: FILSTS 

For MT: SPECL$!SPFUN$ 

For LP: WONLY$ 

7.2.1.4 Device Size Word — The size argument for the .DRDEF macro 
defines the size of the device in 256-word blocks. The .DRDEF macro puts 
this value into ddDSIZ. If the device is not random access, place the value 
in size. The size of the RK device is 4800 decimal blocks (11300 octal); the 
size for the PC (paper tape) device is 0, since it is not random access. 

The .DSTATUS programmed request returns the value of the device size 
word to a running program. For examples of the .DRDEF macro, see the 
device handler listings in Appendix A. 
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7.2.2 Header Section 

The second part of an RT-11 device handler is the header section. In the 
header section you invoke the .DRBEG macro to set up the first five words 
of the handler. This macro also stores five words of information in block of 
the handler file, in locations 52 through 60, and creates some global sym- 
bols, The data you set up in the header section is used when the handler is 
brought into memory with the .FETCH programmed request or LOAD 
monitor command. The contents of location 176, described below, are used 
by the bootstrap when it checks for the presence of device hardware at 
handler installation time. 

7.2.2,1 Information In Block — Table 7-3 shows the five words in block 
that the .DRBEG macro sets up by using the .ASECT directive. It also 
shows the three words .DRBOT sets up for bootable devices (see Section 
7.10,2.6). In the table, the associated mnemonics are shown in square 
brackets, and the two-character device name is represented by dd. 



Table 7-3: Information in Block 

Location Contents [and Mnemonic] 

52 Size of the handler in bytes 

[ddEND-ddSTRT] 

54 Size of the device in 256-word blocks 

[ddDSIZ] 

56 Device status word 

[ddSTS] 

60 A status word to reflect current system generation features 

[ERL$G +<MMG$T*2> + <TIM$IT*4>] 

62 A pointer to the start of the primary driver (from .DRBOT) 

64 The length of the primary driver, in bytes (from .DRBOT) 

66 The offset from the start of the primary driver to the start of the 

bootstrap read routine (from .DRBOT) 

176 GSR address 

[dd$CSR] 



7.2.2.2 First Five Words of the Handler — Table 7-4 shows the five words that 
the .DRBEG macro generates at the start of the handler's p-sect. In the 
table!, dd represents the two-character device name. 

7.2.2.3 .DRBEG Macro — Use tlte .DRBEG macro to set up the information 
in block and the first five words of the handler. This macro also generates 
the appropriate global symbols for your handler. Before you use .DRBEG, 
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you must have invoked .DRDEF to define dd$CSR, drf$VEC, ddDSIZ, and 
ddSTS. The format for .DRBEG is as foUows: 

.DRBEG name 

name is the two-character device name. 

For examples of .DRBEG, see the handler listings in Appendix A. 
Table 7-4: Handler Header Words 

Word Symbol Contents 

1 ddSTRT:: Device vector (for single-vector devices); 

Offset to table of vectors (for multi-vector devices) 

2 Offset to interrupt service entry point 

3 Priority (340) 

4 ddLQE:: Pointer to the last queue element 

5 ddCQE:: Pointer to the current queue element 

7.2.2.4 Muitl-Vector Handlers: .DRVTB Macro — An RT-11 device handler can 
service a device that has more than one vector. The PC handler, for exam- 
ple, services interrupts through vector 70 for the paper tape reader, and 
through 74 for the paper tape punch. 

If your device has more than one interrupt vector associated with it, the 
handler must contain a table of three-word entries for each vector. The en- 
try for each vector consists of the vector location, the interrupt entry point, 
and the Processor Status, or PS, value. 

To set up the handler header for a multi-vector device, simply invoke the 
.DRVTB macro two or more times. The .DRVTB macro sets up the table of 
three-word entries for each vector of a multi-vector device. Place it in your 
handler anywhere between the .DRBEG macro and the .DREND (or 
.DRBOT) macro, as long as it does not interfere with the flow of control 
within the handler. You must invoke this macro once for each vector, and 
the macro calls must appear one after the other in the handler. 

The format of the .DRVTB macro is as follows: 

.DRVTB name,vec,int [,ps] 

name is the two-character device name. Specify it on the first .DRVTB call; 
leave this argument blank on all subsequent calls. 

vec is the location of the vector; it must be between and 474. The first vec- 
tor is usually dd$VEC. The value must be a multiple of 4. 

int is the symbolic name of the interrupt handling routine; it must appear 
elsewhere in the handler. It generally takes the form ddINT, where dd 
represents the two-character device name. 
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ps is an optional value you can use to specify the low-order four bits of the 
new Processor Status word in the interrupt vector. If you omit this argu- 
ment, it defaults to 0. 

An example of a handler that uses two vectors is the PC handler. The 
following example shows the source lines and the code the macros generate. 

; F'UNCH-READER VECTOR TABLE 

.IF EQ PR11$X ;|F BOTH READER AND PUNCH 

.DRVTB PC,PR$VtEC,PRINT ;TABLE FOR READER 

.DRVTB ,PP$VEC,PPINT ;TABLE FOR PUNCH 

.ENDC 



The vector table generated by the .DRVTB macros is as follows: 



.WORD PR$VEC,PRINT-.,340!0 

.WORD PP$VEC,PPINT-.,340!0 

.WORD 



TABLE FOR READER 
TABLE FOR PUNCH 
TO END THE TABLE 



As you see in the example above, the priority bits of the PS are always set 
to 7, even if you omit the ps argument. 

7.2.2.5 PS Condition Codes — In the .DRVTB macro, only the condition 
code bits of theps argument are significant. These can be useful if you have 
a common interrupt service (jntry point for two or more vectors and you 
need to determine through wliich vector the interrupt occurred. For exam- 
ple, the PC handler has separate interrupt entry points for its two vectors, 
so it can easily determine tht; source of the interrupt. Interrupts through 
vector 70 go to the routine at PRINT:; interrupts through 74 go to PPINT:. 

Suppose that the PC handler had only one interrupt entry point, called 
PCINT:. In this case, the handler could distinguish which vector took the 
interrupt by setting the condition codes in the PS for the vectors. For the 
reader vector at 70, it could leave the C bit clear. For the punch vector at 74, 
it could set the C bit. Then, at PCINT:, control could pass to different 
routines based on the value of the C bit in the new PS. The following exam- 
ple shows how to invoke the .DRVTB macro and place values in the condi- 
tion codes of the PS. 



; PUNCH-READER VECTOR TABLE 

.IF EQ PR11$X 

.DRVTB PC,PR$VEC,PCINT 

.DRVTB ,PP$VEC,PCINT,1 

.ENDC 



IF BOTH READER AND PUNCH 
C BIT CLEAR 
C BIT SET 



7.2.3 I/O Initiation Section 

The I/O initiation section contains the first executable instructions of the 
handler. The purpose of the code in this section is to start a data transfer. 
Remember that you must write Position-Independent Code (PIC) for the 
handler. 
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When a program issues a programmed request that requires device I/O, 
such as .READ or .WRITE, control first passes to the Resident Monitor, 
which then calls the device handler for the peripheral device with the JSR 
PC instruction. The monitor calls the handler at the handler's sixth word — 
that is, the first word immediately after the five-word header. It makes the 
call whenever a new queue element becomes the first element in a handler's 
queue. This situation occurs when an element is added to an empty queue, 
or when an element becomes first in a queue because a prior element was 
released. If any of the parameters in the I/O request are invalid for the 
device (for example, the block number is too large, the unit number is too 
high, and so on), the handler should proceed immediately to the I/O comple- 
tion section and signal a hard (fatal) error. 

The I/O initiation code executes at processor priority in system state, 
which means that no context switch can occur, no completion routines can 
run, and any traps to 4 and 10 cause a system fatal halt. AU registers are 
available for you to use in this section. The fifth word of the handler header, 
ddCQE, contains a pointer to the current queue element at its third word, 
Q.BLKN. 

The queued I/O system guarantees that requests for data transfers are 
seriaUzed so that RT-11 device handlers need not be re-entrant. Therefore, 
you can minimize the size of a handler by mixing, rather than separating, 
the pure code and the data segments. 

Guidelines for Starting the Data Transfer 

Since the purpose of the I/O initiation section is to start up the data 
transfer, you must now supply the instructions to do this. The following 
steps represent guidelines for a generalized I/O initiation section. 

1. You should already have decided how many times the handler will 
retry a transfer should an error occur. Initialize a retry counter by mov- 
ing the maximum number of retries to it. The following two lines of 
code illustrate this step. 

MOV #RKCNT,(PC)+ ;RKCNT = MAXIMUM # OF RETRIES 

RETRY: .WORD ;THE RETRY COUNTER 

2. Put the pointer to the current queue element into a register, and get 
the device unit number and the block number for the transfer from the 
queue element. The following lines of code illustrate this. 



MOV 


RKGQE,R5 


;GET POINTER 


MOV 


@R5,R2 


;R2 = BLOCK NUMBER 


MOVB 


Q$UNIT(R5),R4 


;R4 = UNIT NUMBER 


BIG 


#-C<7>,R4 





Next, perform the steps to calculate the address on the device for the 
data transfer to begin. The instructions you use depend on the device s 
structure, of course. Once you have calculated the correct address, 
save it in a memory location. If you need to retry this transfer, you will 
not have to recalculate the address. 
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DISKAD: 



MOV 
.WORD 



R3,(PC) + 




;SAVE ADDRESS IN DISKAD 

;SAVE CALCULATED ADDRESS HERE 



4. Steps 1 through 3 outlined above are executed only once for each data 
I/O request from a running program. However, in case of a soft error, 
you may find it necessary to restart a transfer as part of the retry 
operation. So, by placing a label here to use as the retry entry point, 
you avoid repeating stepis 1 through 3. 

The following steps can be performed more than once: they are ex- 
ecuted once for the first I/O startup, and they can be executed again if 
an I/O error causes a retry. 

At this point the handler should determine whether the I/O request is a 
read, a write, or a seek. It should then generate the appropriate op code 
for the operation and move it to the device control and status register. 
This is the step that actually initiates the I/O transfer. 



CSIE 

FNWRITE = 
CSGO 



100 
1*2 
1 



INTERRUPT ENABLE 

WRITE 

GO BIT 



AGAIN: MOV 
MOV 
MOV 



RKCQE,R5 

#CSIEIFNWRITEICSG0,R3 

#RKDA,R4 



POINT TO QUEUE ELEMENT 
ASSUME A WRITE 
POINT TO DISK 
ADDRESS REGISTER 



5. Finally, return to the iaterrupted program by going through the 
monitor first. Then when the I/O transfer finishes, the device will inter- 
rupt, and control will pass to the handler at the interrupt entry point in 
the interrupt service section of the handler. 



RTS 



PC 



;AWAIT INTERRUPT 



7.2.4 Interrupt Service Section 

Control passes to the interrupt service section of the handler when a device 
interrupts or when the program requesting the I/O transfer aborts. The code in 
this section must first determine if the data transfer had an error, if it was 
incomplete, or if it was complete, and then take the appropriate action. The 
same register usage restrictions that apply to the interrupt entry point also 
apply to the abort entry point (see Table 6-3). 

Yovir first step in coding the interrupt service section is to set up the inter- 
rupt entry point and the abort entry point by using the .DRAST macro. 
(These entry points are sometimes referred to as the asynchronous trap en- 
try points.) The default name for the interrupt entry point is ddlNT, where 
dd is the device name. Under normal conditions, the handler is called at the 
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interrupt entry point when an interrupt occurs. However, under some cir- 
cumstances, the handler is called at the abort entry point. The various 
situations are discussed in the following sections. 

7.2.4.1 Abort Entry Point — There are a number of situations that cause an 
abort in the queued I/O system: (1) a double CTRL/C can abort a running 
program; (2) the .HRESET programmed request causes an abort; (3) a trap to 
4 or 10, or any other condition that produces the IMON-F- type of fatal error 
message, also causes an abort. On abort, whether or not the handler is entered 
at all depends on two factors. The handler is always entered at the abort entry 
point (the word immediately before the normal interrupt entry point) if an 
active queue element exists and it belongs to the aborting job. In FB and XM, 
the handler is also entered regardless of the existence of a queue element if 
HNDLR$ (bit 11) is set in the device status word. The SJ monitor ignores this 
bit. Additionally, handlers are never entered when a job aborts in the SJ 
environment; the SJ monitor simply performs a RESET instruction. In all 
environments, on entry to the handler, R4 always contains the job number of 
the aborting job. 

When an abort occurs, it is important to stop I/O on some devices. 
Character-oriented devices, such as the paper tape reader/punch, fall into 
this category. On abort, the handler must stop the device in order to pre- 
vent a tape runaway condition, for example. It must also make sure that the 
device cannot interrupt again. So, character-oriented devices generally con- 
tain an abort routine; the abort entry point is simply a branch instruction to 
that routine. The PC handler, for example, has an abort routine that 
disables interrupts on the paper tape reader/punch. Then the handler exits 
to the monitor in the I/O completion section. The following Une is from the 
PC handler (PRCSR is a word in the handler that points to the CSR): 

PRDONE: CLR ©PRCSR JURN OFF THE READER/PUNCH INTERRUPT 

Other devices, such as disks, should be allowed to complete an I/O transfer 
attempt, even if an abort occurs. In fact, trying to abort in the middle of an 
operation can corrupt data or formatting information on a disk. So, instead 
of having a separate abort routine, most handlers for disks ignore an abort. 
Thus, an RTS PC instruction is located at the abort entry point, which 
simply returns control to the monitor. 

If you use .FORK in your handler, there is a special procedure you must 
follow if an abort occurs. You must move to F.B ADR (the fork routine ad- 
dress, at offset 2) in the fork block. This prevents the monitor from attempt- 
ing to execute a meaningless fork routine after the abort. 

7.2.4.2 Lowering the Priority to Device Priority — When the interrupt occurs, 
the handler is entered at priority 7. As with interrupt service routines, the 
handler's first task is to lower the processor priority to the priority of the 
device, thus permitting more important devices to interrupt this service 
routine. Instead of using the .INTEN call, as in an interrupt service routine, 
use the .DRAST macro to lower the priority. 

7.2.4.3 .DRAST IVIacro — Use the .DRAST macro to set up the interrupt en- 
try point and the abort entry point, and to lower the processor priority. The 
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macro also sets up a global symbol $INPTR, which contains a pointer to the 
$INTEN routine in the Resident Monitor. This pointer is filled in by the 
bootstrap (for the system device) or at .FETCH time (for a data device). 

The format of the .DRAST macro is as follows: 

.DRAST name,pri[,abo] 

name is the two-character device name. 

pri is the priority of the device, and the priority at which the interrupt ser- 
vice code is to execute, as well. 

abo is an optional argument that represents the label of an abort entry 
point. If you omit this argument, the macro generates an RTS PC instruc- 
tion at the abort entry point, which is the word immediately preceding the 
interrupt entry point. 

The following example from the PC handler shows the .DRAST macro call 
and the code it generates. 



.DRAST 


PP,4,PRD0NE 






.GLOBL 


$INPTR 




;MAKE THIS SYMBOL GLOBAL 


BR 


PRDONE 




;THE ABORT ENTRY POINT 


PRINT:: JSR 


R5,@$INPTR 




;JUMP TO MONITOR INTEN CODE 


.WORD 


-C<4*-O40>Jk 


^•0340 


;NEW PRIORITY 



The next example, from the RK handler, does not have an abort routine. 

.DRAST RK,5 



.GLOBL 


$INPTR 


RTS 


PC 


RKINT:: JSR 


R5,@$INPTR 


.WORD 


-^C<5* '^O40>& 



^0340 



MAKE THIS SYMBOL GLOBAL 
JUST RETURN ON ABORT 
JUMP TO MONITOR INTEN CODE 
NEW PRIORITY 



7.2.4.4 Guidelines for Coding the interrupt Service Section — Since the purpose 
of this section is to evaluate thes results of the last device activity, you must 
now supply the instructions to do this. Essentially, the code must deter- 
mine if the transfer was in error, if it was incomplete, or if it was complete. 

1. // an Error Occurred 

If an error occurred during the transfer, the handler must distinguish 
between a hard error and a soft error that might vanish if the operation 
lis retried. 

If the error is hard, the handler should immediately exit through the 
I/O completion section. 

If the error is soft, the handler should prepare to retry the transfer. It 
should decrement the count of available retries. Then, at fork level, it 
should branch back to the I/O initiation section to restart the transfer. 
If the transfer has akeady been retried enough times (the retry count is 
0), treat the failure as though it were a hard error. In that case, the 
handler should proceed to the I/O completion section. 
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Note that dropping to fork level is not strictly required to process an 
error. Whether or not to use .FORK depends on the length of time re- 
quired for setting up the retry. The .FORK call is especially useful 
because it gives you use of RO through R3, thus permitting you to use 
common routines for the retry. If you do not use .FORK, only R4 and 
R5 £ire available. 

Perform Retries at Fork Level 

As you learned in Chapter 6, the .FORK macro causes a return to the 
Resident Monitor, which dismisses the current interrupt. (Review Sec- 
tion 6.5.6 for details on the .FORK macro.) The code that follows 
.FORK executes at priority 0, rather than at device priority, after all 
other interrupts have been serviced, but before any jobs or their com- 
pletion routines can execute. The code following .FORK executes, as 
does the main body of the interrupt service section of the handler, in 
system state. (This is the same state the I/O initiation section runs in.) 
Thus, context switching is prevented while the fork level code is ex- 
ecuting, and any traps to 4 and 10 cause a system fatal halt. 

The following example from the RK handler illustrates how the handler 
drops priority to fork level to retry data transfers after a soft error oc- 
curred. Fork level is ideal for performing the retries, since this may be a 
lengthy process. The .FORK call and its expansion are as follows: 



.FORK RKFBLK 



;THE FORK CALL 



JSR 
.WORD 
RKRETR: CLRB 
BR 



R5,®$FKPTR 
RKFBLK -. 
RETRY + 1 
AGAIN 



(JUMP TO MONITOR FORK CODE) 
(OFFSET TO FORK QUEUE ELEMENT) 
RESET A FLAG 
BRANCH INTO I/O INIT SECTION 



If the Transfer Was Incomplete 

In general, a transfer is considered to be incomplete when there are 
more characters or more blocks of data left to transfer. The handler 
should restart the device and exit with an RTS PC instruction to wait 
for the next interrupt. 

// the Transfer Was Complete 

When the transfer is complete, the handler can simply exit through the 

I/O completion section. 



7.2.5 I/O Completion Section 

The I/O completion section provides a common exit path to inform the 
monitor that the handler is done with the current request, so that the 
monitor can release the current queue element. Although the other sections 
of the handler are distinct, separate parts, the I/O completion section is ac- 
tually an extension of the interrupt service section and the dividing line be- 
tween these two sections is artificial. Control does not pass to the I/O com- 
pletion section as a result of a monitor call, a subroutine call, or a jump, but 
rather as a result of normal flow of execution through the interrupt service 
section. Execution passes to the I/O completion section when a hard error is 
detected, when a soft error condition exhausts the number of retries allowed 
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for it, or when a data transfer completes. (Note that you can branch directly 
to this section from the I/O initiation section if you detect a hard error 
immediately.) 

1. If an Error Occurred 

There are two kinds of err(5rs that cause control to pass to the I/O com- 
pletion section: hard errors, which should cause a branch to this section 
immediately, and soft errors that have exhausted their allotted 
number of retries, which cause a branch to this section after the last 
retry fails. Treat both cases alike in handling the exit to the monitor. 
First, set the hard error bit, bit 0, in the Channel Status Word for the 
channel. The second word of the I/O queue element, Q.CSW, points to 
the Channel Status Word. Then jump to the I/O completion routine in 
the Resident Monitor. Use the .DRFIN macro, described below, to 
generate the code for this jump. 

The following lines of code are from the RK handler. They illustrate 
how the handler sets the hard error bit and jumps back to the monitor. 



BIS 



#HDERR$,@-(R5) 



.DRFIN RK 



SET HARD ERROR BIT 
(R5 POINTS TO THIRD WORD OF 
QUEUE ELEMENT; POINTER TO 
CSW IS SECOND WORD.) 
JUMP TO MONITOR 



// the Transfer Was Complete 

For a block-oriented device, such as a disk or diskette, the handler 
simply disables interrupts and performs the jump to the monitor. As 
the example in point 2 shows, the .DRFIN macro generates the code to 
perform the jump. 

IPor a character or word-oidented device, such as paper tape, the pro- 
cedure is slightly more coimplicated because the handler may have to 
report end-of-file to the job that requested the I/O transfer. Examples 
of conditions that cause end-of-file are absence of tape in the paper tape 
reader, and detection of CTRL/Z typed on the console terminal. When 
the handler actually detects the EOF condition on a READ operation, 
it should set an internal EOF flag, put the last character in the user's 
buffer, and then zero-fill the rest of the buffer. Then the handler should 
jump back to the monitor, as it would if EOF were not detected but the 
buffer had simply filled up. The handler waits until it is called again to 
signal EOF to the user. 

The PC handler uses the reader/punch ready bit in the device status 
register as the internal EOF flag. The following example shows how 
t;he PC handler zero-fills the user buffer when it detects end-of-file, sets 
an internal EOF flag, and jumps back to the monitor. 



PRE01: CLRB 



@(R4) + 



INC 


■(R4) 


DEC 


BYTCNT-BUFF(R4) 


BNE 


PRE01 


F'RDONE: CLR 


@PRCSR 


F>RFIN: .DRFIN 


PR 



CLEAR REMAINDER OF BUFFER 

(R4 POINTS TO BUFFER ADDRESS) 

BUMP BUFFER ADDRESS 

TEST IF DONE 

BRANCH IF MORE 

TURN OFF DEVICE INTERRUPT 

JUMP TO MONITOR 
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When the handler is called again with a new queue element for another 
READ operation, it first checks its internal EOF flag. Finding it set, 
the handler sets the EOF bit of the Channel Status Word, bit 13, and 
jumps back to the monitor. The Resident Monitor eventually clears 
this bit, when the next I/O request is made for this channel. 

The following example shows how the PC handler tests the device 
ready bit — which it uses as its internal EOF flag — sets the EOF bit 
for the user program, and jumps back to the monitor. 



TST @#PR$CSR 

BPL PRGORD 

BIS #E0F$,@-(R4) 

BR PRDONE 



IS READER READY? 
;YES, START TRANSFER 
NO, SET EOF BIT 
GO TO COMPLETION 



PRDONE: CLR ©PRCSR ;TURN OFF DEVICE INTERRUPT 

PRFIN: .DRFIN PR ;JUMP BACK TO MONITOR 

This convention for indicating end-of-file makes character-oriented 
devices appear to programs as random-access devices, which is in keep- 
ing with the RT-11 philosophy of device independence. 

.DRFIN Macro 

Use the .DRFIN macro to generate the instructions for the jump back to 
the monitor at the end of the handler I/O completion section. The macro 
makes the pointer to the current queue element a global symbol, and it 
generates Position-Independent Code for the jump to the monitor. When 
control passes to the monitor after the jump, the monitor releases the cur- 
rent queue element. 

The format of the .DRFIN macro is as follows: 

.DRFIN name 

name is the two-character device name. 

For examples of the .DRFIN macro, see the handler listings in Appendix A. 

7.2.6 Handler Termination Section 

The purpose of the handler termination section is to declare some global 
symbols and to establish a table of pointers to offsets in the Resident 
Monitor. The pointers are filled in by the bootstrap, if the handler is for the 
system device. Otherwise, they are filled in when the handler is made resi- 
dent with .FETCH or LOAD. The termination section also provides a sym- 
bol to determine the size of the handler. Use the .DREND macro to generate 
the handler termination code. 

7.2.6.1 .DREND Macro — The format of the .DREND macro is as follows: 
.DREND name 
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name is the two-character devic:e name. 

For examples of the .DREND macro, see the handler listings in Appen- 
dix A. 

7.2.6.2 Pseudo- Devices — You can write a device handler for a pseudo- 
device (one that does not interrupt, and is not a mass storage device) to take 
advantage of the queued I/O system and the fact that handlers can remain 
memory resident. Examples of handlers for pseudo-devices are NL (the null 
devic(}) and MQ (the message queue handler). 

All the executable code of such a handler must appear in the I/O initiation 
section. The handler should then issue the .DRFIN macro call to terminate 
the operation and return the queue element. Since pseudo-devices do not in- 
terrupt, the handler needs no iinterrupt service section, and no .DRAST 
macro call. 

7.3 Skeleton Outline of a Device Handler 

The skeleton outline in Figures 7-1 provides the structure for a simple 
device handler. In the figure, SK is the device name. 

Figure 7-1: Skeleton Device Hiindler 

•TITLE SK y04.01 

) SK DEVICE HANDLER 

.IDENT /y04,01/ 

•SBTTL PREAMBLE SECTION 

.MCALL .DRDEF 

.DRDEF SKr377.U0NLY*.0il77514r200 

SKBR = SK»CSR+2 SSK BUFFER REGISTER 

SKIE = 100 (INTERRUPT ENABLE BIT 

.SBTTL HEADER SECTION 

.DRBEG SK 

.SBTTL I/O INITIATION SECTION 

MOM SKCBE,R4 ;R4 POINTS TO CQE 

ASL Q$WCNT<R4) ! MAKE WORD COUNT BYTE COUNT 

BEQ SKDONE iA SEEK COMPLETES IMMEDIATELY 

BCC SKERR iTHIS IS A WRITE-ONLY DEVICE - 

>A READ REQUEST IS ILLEGAL 

RET! BIS *SKIEr0*SK*CSR (ENABLE INTERRUPTS 

RTS PC (WAIT FOR ONE 

•SBTTL INTERRUPT SERVICE SECTION 

•DRAST SK.4rSKD0NE 

MOV SKC0EiR4 ;R4 POINTS TO CQE 

BIT ♦100200ie»SK*CSR (ERROR OR READY? 

BMI RET (ERROR - HANG UNTIL CORRECT 

BEQ RET (NOT READY - EXIT AND WAIT 

BIC *SKIEje»SK»CSR (DISABLE INTERRUPTS 

•FORK SKFBLK (PROCESS REMAINING CODE AT 

(FORK LEVEL 

ADD *Q*WCNTfR4 (OFFSET QUEUE ELEMENT POINTER 
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Figure 7-1: Skeleton Device Handler (Cont.) 



SKNEXT! 


TSTB 


e*SK»CSR 




BFL 


RET 




TST 


8R4 




EIL'» 


SKDONE 




MOVB 


e-<R4) .R5 




INC 


(R4) + 




INC 


QRA 




BIC 


*"C<177>fRS 




MOVB 


R5.e»SKBR 




BR 


SKNEXT 


.SBTTL 


I/O COMPLETION SECTION 


skerr: 


BIS 


*HriERRtr@-(R4) 


skdone; 


BIC 


*IEie*SK4CSR 




•DRFIN 


SK 


skfeilk: 


.UORB 


Of 0»0»0 



(READY FOR NEXT CHAR? 
JNO - BRANCH BACK 
(ANY LEFT TO PRINT? 
(NO - TRANSFER IS DONE 
(GET A CHARACTER 
(BUMP BUFFER POINTER 
(BUMP CHARACTER COUNT 
(7-BIT ASCII 
(SEND CHAR TO DEVICE 
(TRY FOR ANOTHER 



(SET ERROR BIT IN CSU 
(DISABLE INTERRUPTS 
(JUMP TO MONITOR 



(FORK QUEUE ELEMENT 
.SBTTL HANDLER TERMINATION SECTION 

.DREND SK 
, END 



7.4 Handlers That Queue internally 

A device handler can maintain one or more of its own internal queues of 
outstanding I/O requests instead of using the usual monitor/handler I/O 
queue. The purpose of maintaining an internal queue is that it permits 
several operations to take place on the device simultaneously — that is, the 
handler can service several requests to access the device at once. 

As an example, consider a process controller with input counters and an 
A/D converter. Since the converter is a slow device, the IP-11 controller can 
read an input counter while running the converter. Another example is the 
RT-11 message queue, implemented through the MQ handler, for system 
job communication. If one job sends a message to a second job, and the sec- 
ond job does not accept the message, the MQ handler waits. However, if a 
receive request for the job is next in the queue, the MQ handler processes it. 
To do this, it takes the original send request from the monitor/handler 
queue, queues it internally, and then services the receive request. 

In general, the handler follows a simple procedure to implement internal 
queuing. When an I/O request is made for the handler, it is always the first 
and only request in the monitor/handler queue. As soon as it comes in, the 
handler queues it internally and clears ddCQE and ddLQE to "remove" the 
request from the monitor/handler queue. Note that the queue element is 
still busy — it is still in use by the handler. 

7.4.1 Implementing Internal Queuing 

When the handler is first entered for a request, at the sixth word, it must 
check the queue element for validity. An invalid request causes an im- 
mediate fatal error. 

If the request is for a procedure that completes very quickly, such as a seek 
on paper tape, the handler performs the operation. Then it issues the 
.DRFIN macro call to release the queue element and inform the requesting 
program that the operation completed. In summary, the handler performs 
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the operation if it is one that can be taken care of both synchronously and 
quickly. 

If the request is for a procedure that requires calculation and some time to 
complete, the handler places the request on its internal queue by using the 
queue element's Unk word. The Unk word is 0, because this element is the 
first and only element on the queue. 

In summary, the handler queues the request internally if it is one that re- 
quires some work and time, and must be taken care of asynchronously. If 
the request is the first one on the internal queue, the handler starts the 
operation, waits for it to complete, and exits with an RTS PC instruction. If 
the request is not the first one on the internal queue, the handler does not 
start the operation and simpl;^^ exits with an RTS PC instruction. 

7.4.2 Interrupt Service for Handlers That Queue Internally 

When an operation completes, the handler is entered at its interrupt entry 
point, ddINT:. After this, various actions are taken depending on the cir- 
cumstances. If there is more than one internal queue, the handler deter- 
mines which request this interrupt involves. If the operation is not com- 
plete, the handler restarts it and returns to the monitor. If the transfer is 
complete, the handler must put the internally queued request back on the 
monitor/handler I/O queue by setting ddCQE and ddLQE. In this situation, 
the handler needs to return the request to the main I/O queue, but it also 
needs to continue execution (rather than return immediately to the monitor) 
to check its internal queue in case there is another outstanding request. 

To return the request to the monitor without exiting, the handler must per- 
form a .DRFIN substitute. The following example illustrates how a handler 
does this. 

R4 points to the queue element on the internal queue, at its third word. 



MOV ddCQE,-(SP) 



MOV 


R4,cldCQE 


MOV 


R4,ddLQE 


GLR 


Q$LINK(R4) 


MOV 


PC,R4 


ADD 


#ddCQE-.,R4 


MOV 


@#54,R5 


JSR 


PC,@270(R5) 


MOV 


©SP.ddCQE 


MOV 


(SP) + , ddLQE 



IN CASE THE MONITOR/HANDLER QUEUE 
HAS AN ELEMENT WHEN WE TAKE THIS 
INTERRUPT 

PUTS INTERNAL QUEUE ELEMENT ON THE 
MONITOR/HANDLER QUEUE 

JSR 

VERSION 
OF 

.DRFIN 
RESTORE POSSIBLE OTHER 
QUEUE ELEMENT 



(Check the Internal queue now and start another operation If necessary.) 

RTS PC ;RETURN 
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7.4.3 Abort Procedures for Handlers That Queue Internally 

Whether or not your handler queues I/O requests internally, RT-11 maintains 
a count of outstanding I/O requests for each channel. There is one counter in 
each channel; the total of outstanding I/O requests is in the Resident Monitor. 
When a job aborts, any outstanding I/O requests it has must be removed from 
the counters. This occurs automatically if the handler relies strictly on the 
monitor/handler I/O queue. 

If, however, the handler implements an internal I/O queue, it must follow a 
procedure to reduce the count of outstanding I/O requests. This procedure 
involves making sure that the handler will be entered when any job aborts, 
whether or not the handler appears to have an active queue element, by 
having the handler set bit 11, HNDLR$, in the device status word ddSTS 
when it invokes .DRDEF. In FB and XM systems, this forces the handler to 
be entered on all aborts, even if there is nothing on its monitor/handler queue. 
(The SJ monitor ignores this bit, since there is no problem in a single-job 
system.) 

If the handler is entered at the abort entry point, then, it must check its 
internal queue for elements belonging to the aborted job. (Remember that R4 
always contains the job number of the aborting job.) The handler should 
purge its internal queue of these elements and use one of the following proce- 
dures to reduce the monitor's count of outstanding I/O requests. 



If ddCQE has a non-zero value: 

1. Remove any internal elements for the aborting job. 

2. Link the elements together via the element's link word; the last element's 
link word must be 0. Set ddLQE to point to the last element in the 
aborting job. 

3. If ddCQE points to an element belonging to the aborting job, halt I/O and 
issue a .DRFIN. If you cannot halt I/O, then issue an RTS PC instruction, 
wait for an interrupt, and then issue a .DRFIN. 

If ddCQE does not point to an element belonging to the aborting job, 
simply issue the RTS PC instruction. 



If ddCQE has the value 0: 

1. Remove any internal queue elements that belong to the aborting job. If 
there are none, simply issue the RTS PC instruction. 

2. Link the elements together, as described in 2 above, setting ddCQE to 
point to the first element, and ddLQE to point to the last element. Note 
that the last element's link word must be 0. 

3. Issue the .DRFIN macro. 
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7.5 SET Options 



The keyboard monitor SET command permits you to change certain charac- 
teristics of a device handler. The handler must exist as a dd.SYS file on the 
system device (ddX.SYS for XM), where dd is the two-character device 
name. For example, the following command changes the column width for the 
line printer: 

SET LP WIDTH=80 (The default is 132 columns) 

Another type of SET command can enable or disable a function. The follow- 
ing example shows how a SET command can cause the system to send car- 
riage returns to the line printer or to refrain from sending them. 

SET LP CR (Send carriage returns; this is the default) 

SET LP NOCR (Does not send carriage returns) 

Note that you negate the CR option by adding NO to the start of the option. 
See Chapter 4 of the RT-11 System User's Guide for more information on the 
SET options available with existing RT-U device handlers. 
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A device handler you write can contain code to implement different options. 
Follow the format outlined in the following sections to learn how to add 
SET options to your handler. Adding a SET option affects only the handler 
file; you need not make any changes to the monitor. Note that SET options 
are valid for both data and system devices. 



7.5.1 How the SET Commaind Executes 

The SET command is driven entirely by a table in block of the handler file, 
and by a set of routines, also in block 0, that modify instructions and data in 
blocks and 1 of the handler. Flemember that block refers to addresses 
through 776, and that the handler header starts in block 1 at location 1000 
in th(} file. 

When you type a SET command at the console terminal, the monitor parses 
the command line and looks J or the handler file dd.SYS on the system 
device (ddX.SYS in XM). This handler need not be installed in the running 
system. The monitor then reads blocks and 1 of the handler into the USR 
buffer area in memory. It scans the table in block until it finds the table 
entries for the SET option yoiJi specified. From the table entry it can find 
the particular routine designed to implement that option and the modifiers 
permitted by that routine, such as NO or a numeric value. The monitor then 
exec\ites the routine, which contains instructions that modify code in 
blocks or 1 of the handler. The code in block 1 is part of the body of the 
handler and contains the instructions for the default settings of all the SET 
options. After the code is modified, the monitor writes blocks and 1 back 
out to the system device. Thus, as a result of the SET command, some in- 
structions or data in the handler are changed. 



7.5.2 SET Table Format 

The t;able for the SET options (consists of a series of four-word entries, with 
one entry per option. The table begins at location 400 in block of the 
handler and ends with a zero word. Use the .DRSET macro, described 
below, to generate the table. 

The first word of the table is a value to be passed in R3 to the SET routine 
associated with the option when the monitor processes this option. This 
word can be a numeric value — such as the default column width for the line 
printer — or it can be an instruction to substitute for another instruction in 
block 1 of the handler. It must; not be 0. 

The second and third words of the table are the Radix-50 code for the option 
name, such as WIDTH or CR. In the table, the characters are left-justified 
and filled with spaces. 

The low byte of the fourth word is a pointer to the routine that performs the 
code modification. The high byte indicates the type of SET parameter that 
is valid. Setting the 100 bit shows that a decimal argument is required. A 
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value of 140 shows that an octal argument is required. Setting the 200 bit 
means that the NO prefix is valid for this option. 

Figure 7-2 shows a summary of the SET option table. 
Figure 7-2: SET Option Table 



VALUE TO PASS IN R3 
TO THE SET ROUTINE 


RADIX-50 FOR OPTION NAME 
(TWO WORDS) 


CODE FOR VALID SET 
COMMAND TYPES 


POINTER TO SET 
ROUTINE 



7.5.3 .DRSET Macro 

Use the .DRSET macro to set up the option table by calling the macro once 
for each option so that the macro calls appear one after the other. You must 
use the .DRSET macro after .DRDEF and before the .DRBEG macro. 

The format for the .DRSET macro is as follows: 

.DRSET optlon,val,rtn[mode] 

option is the name of the SET option, such as WIDTH or CR. The name can 
be up to six alphanumeric characters long and should not contain any 
embedded spaces or tabs. 

vol is a parameter that will be passed in R3 to the routine. It can be a 
numeric constant, such as the minimum column width, or an entire instruc- 
tion enclosed in angle brackets to substitute for an existing one in block or 
1 of the handler. It must not be 0. 

rtn is the name of the routine that modifies the code in block or 1 of the 
handler. The routine must follow the option table in block and must not go 
above address 776. 

mode is an optional argument to indicate the type of SET parameter. Enter 
NO to indicate that a NO prefix is vaUd for the option. Enter NUM if a 
decimal value is required. Enter OCT if an octal value is required. Omitting 
the mode argument indicates that the option takes neither a NO prefix nor 
a numeric argument. You can combine the NO and numeric arguments as 
follows. The construction<NO,NUM>indicates that either a NO prefix or 
a decimal value is required (but not both). The construction<NO,OCT>in- 
dicates that either a NO prefix or an octal value is required (but not both). 
Omitting the mode argument forces a into the high byte of the last word 
of the table entry. 
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See the sections below for examples of the .DRSET macro. 

The first .DRSET macro issues an .ASECT directive and sets the location 
counter to 400 for the start of the table. The macro also generates a zero 
word for the end of the table. Because the macro leaves the location counter 
at the end of the table, you sltiould place the routines to modify code im- 
mediately after the .DRSET macro calls in your handler. This makes sure 
that they are located in block of the handler file. 



7.5.4 Routines to Modify the Handler 

Your handler needs one routim; for each SET option that is valid. You need 
only one routine for an option and the NO version of that option. The pur- 
pose of the routine is to modify code in the body of the handler based on the 
SET command typed on the console terminal. 

The routines must immediately follow the option table, described above, 
and they must be located in block 0, after the table and below address 1000. 
The code in the body of the handler that the routines modify must be in 
block 1 of the handler, within the first 256 decimal words. 

The name of the routine is its default entry point. This is the entry point for 
options that take a numeric value, for options that take neither a numeric 
values nor a NO prefix, and for options that accept a NO prefix but do not 
currently have it. The entry point for options that allow and have a NO 
prefix is the default entry point + 4. 

On entry to the routine, for all options, R3 contains the val word of the op- 
tion table and the carry bit is clear. In addition, if numeric values are valid 
for this option, RO contains a numeric value from the SET command Une. 

The routine can indicate that a command is illegal by returning with the 
carry bit set. For example, the line printer SET WIDTH option does not 
allow a width less than 30. If the option routine indicates failure, the 
monitor prints an error message and does not write out blocks and 1. 
Thus, the check can be made after the block 1 code is modified. 

Once you have added the routines for each option to your handler, you can 
use the following line of code to make sure you are within the size bounds: 

.IIFGT,<.-1000>, .ERROR. -1000 ; SET code too big! 

You terminate this section with an .ASECT directive, after which you set 
the location counter to 1000. Then you can continue with the rest of the 
handler code, starting with thie .DRBEG macro, which establishes the 
handler header. 



7.5.5 Exampies of SET Options 

The following examples taken fr om the line printer handler are implementa- 
tions of SET options. 
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The examples were chosen to reflect the SET command examples shown at 
the beginning of this section. The SET commands were as follows: 

SET LP WIDTH = 80 
SET LP CR 
SET LP NOCR 

First, the handler invokes the .DRSET macro to set up the option tables for 
the two options WIDTH and CR. 

The first call indicates that the line printer WIDTH option is being 
estabUshed, that 30 decimal is a default value of some kind, that O.WIDTH 
is the routine that modifies code for it, and that it takes a numeric argu- 
ment: 

.DRSET WIDTH,30.,O.WIDTH,NUM 

The next call indicates that the Une printer CR option is being established, 
that "NOP" is to be passed to the routine, that O.CR is the name of the 
routine that modifies code for this option, and that the CR option can take a 
NO prefix: 

.DRSET CR,NOP,O.CR,NO 

The two macro calls generate the following table: 



ASECT 








= 400 










.WORD 


30. 


;MINIMUM WIDTH 




.RAD50 


\WIDTH \ 


lOPTION NAME 




.ElYTE 


<O.WIDTH-400>/2 






.BYTE 


100 






NOP 




;INSTRUCTION TO PASS 




.RAD50 


\CR \ 


;OPTION NAME 




.BYTE 


<O.CR-400>/2 






.BYTE 


200 






.WORD 





;END OF TABLE 



The routines to process these options immediately follow the end of the 
table. The following examples show the routines. The body of the code in 
block 1 of the handler that the routines modify is shown at the end of the 
section. 



O.WIDTH: 



MOV 
MOV 
CMP 

RTS 



RO.COLCNT 
R0,RSTC + 2 
R0,R3 

PC 



MOVE VALUE FROM USER TO 
TWO CONSTANTS 
COMPARE NEW VALUE TO 
MINIMUM WIDTH, 30. 
RETURN; C BIT SET ON ERROR 



Note in the example above that the instructions in the routine O.WIDTH 
change data in two locations in block 1 of the handler. 



TOR: MOV (PC) + ,R3 

BEG RSTC-CROPT+. 



ENTRY POINT FOR "CR"; MOVE 
ADDRESS OF NEXT LINE TO R3 
A NEW INSTRUCTION 
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MOV 



RTS 



R3,CR0PT 



PC 



ENTRY POINT FOR 
"NOGR"(O.CR + 4); 
MOVE EITHER "NOP" OR 
PREVIOUS LINE TO CROPT 
RETURN 



NOTE 

While executing the routines to process a SET option, R4 and 
R5 are not available for use. 

The routine O.CR has two entry points: for the "CR" option, the routine is 
entered at O.CR; for the "NOCR" option, the routine is entered at O.CR 
+ 4, Note that (1) the routine manages to substitute one of two instructions 
for an instruction located in block 1; (2) a NOP instruction is moved to 
CROPT if the "NOCR" option is selected; (3) if "CR" is selected, the BEQ 
RSTC-CROPT + . instruction is moved to CROPT. 

The construction of the BEQ instruction is necessary because the branch is 
being assembled into a location other than the one from which it will be ex- 
ecuted. In all the routines, a branch instruction must use the following con- 
struction to generate the correct address: 

BR A-B + . 

A is the destination of the branch instruction. 

B is the address of the branch instruction. 

. is the current location counter. 

Generally, only routines for options that accept NO use these branch 
instructions. 

Finally, look at the code in th(; interrupt service section of the handler that 
is modified by the routines you have just seen. Remember that the code to 
be modified must be located in block 1 of the handler, in the first 256 
decimal words. 



;# OF PRINTER COLUMNS LEFT 



IS CHAR TAB? 

YES, RESET TAB 

IS IT LINE FEED? 

YES, RESTORE COLUMN COUNT 

IS IT CARRIAGE RETURN? 

"NOP" IF "NOCR" OPTION; 

ELSE IF "CR" OPTION, USE 

"BEQ RSTC-CROPT + ." FROM 

SET ROUTINES IN BLOCK 0. 

IS IT FORM FEED? 

NO, IT IS NON-PRINTING 

RE-INIT COLUMN COUNTER 

From the examples in the first part of this section, you can see how the 
routines in block can modiify data and instructions in block 1 of the 
handler. 



COLCNT: 


-WORD 


COLSIZ 


CHRTST: 


CMPB 


R5,#HT 




BEQ 


TABSET 




CMPB 


R5,#LF 




BEQ 


RSTC 




CMPB 


R5,#CR 


CROPT: 


NOP 






CMPB 


R5,#FF 




BNE 


IGNORE 


RSTC: 


MOV 


#COLSIZ,COLCNT 
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7.6 Device I/O Time-out 



Through the optional feature device time-out, a handler can assign a com- 
pletion routine to be executed if an interrupt does not occur within a 
specified time interval. Thus, the handler can perform the equivalent of a 
mark time operation without the need for a .SYNCH call and its attendant 
potential delay. 

You can select the device time-out feature at system generation time. Time- 
out is used by parts of the RT-11 multi- terminal monitor. The option is 
automatically included in your system if you select multi-terminal time-out 
support or DZ modem support. Otherwise, if you need to use the feature in 
your handler, you must specifically include it at system generation time. It 
is also required for DECnet applications. 

RT-11 provides two macros to help you implement device time-out in your 
handler. The macros, which are described below, are .TIMIO and .CTIMIO. 
They are available only to device handlers. If you assemble the handler file 
with the conditional TIM$IT equal to 1, the .DRDEF macro issues an 
.MCALL directive for the .TIMIO and .CTIMIO macros. 



7.6.1 .TIMIO Macro 

Use the .TIMIO macro in the handler I/O initiation section to issue the 
time-out call. You can issue the request anywhere in the handler except at 
interrupt level. If you need to issue the request at interrupt level, you must 
issue a .FORK macro call first. 

The .TIMIO request schedules a completion routine to run after the 
specified time interval has elapsed. The completion routine runs in the con- 
text of the job indicated in the timer block. In XM systems, the completion 
routine executes with kernel mapping, since it is still a part of the interrupt 
service routine. (See Section 6.7 for more information about interrupt ser- 
vice routines and the XM monitor.) As usual with completion routines, RO 
and Rl are available for use. When the completion routine is entered, RO 
contains the sequence number of the request that timed out. 

Because you must go to fork level (and processor priority 0) to issue a 
.TIMIO or .CTIMIO request, your handler must disable device interrupts 
before issuing the .FORK, or must be carefully coded to avoid reentrancy 
problems. Note that you cannot reuse a timer block until either the timer 
element expires and the completion routine is entered, or the timer element 
is cancelled successfully. 

The format of the macro is as follows: 

TIMIO tbk,hi,lo 

tbk is the address of the timer block, a seven-word pseudo timer queue ele- 
ment, described below. Note that you must not use a number sign (#) before 
tbk. 

hi is a constant specifying the high-order word of a two-word time interval. 



^ 
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lo is a constant specifying the low-order word of a two-word time interval. 
The timer block format is shown in Table 7-5, 



Tablie 7-5: Timer Block Format 
Offset Name Agent 



Contents 



C.HOT .TIMIO 

2 CLOT .TIMIO 

4 CLINK monitor 

6 CJNUM user 

10 CSEQ user 



12 
14 



CSYS 
C.COMP 



monitor 
user 



High-order time word 

Low-order time word 

Link to next queue element; indicates 
none. 

Owner's job number; get this from the 
queue element. 

Sequence number of timer request. The 
vahd range for sequence numbers is from 
177400 through 177477. 

-1 

Address of the completion routine to ex- 
ecute if time-out occurs. The monitor zeroes 
this word when it calls the completion 
routine, indicating that the timer block is 
available for reuse. 



Although the .TIMIO macro moves the high- and low-order time words to 
the timer block for you, you must take care to specify them properly in the 
macro call. Express the time interval in ticks. There are 60 decimal ticks per 
second if your system is running with 60-cycle power. If your system is run- 
ning with 50-cycle power, there are 50 decimal ticks per second. Time values 
for 50-cycle power are shown in square brackets ([ ]) immediately after the 
60-cycle figure. 

The low-order time word accomodates values of up to 65535 ticks. That is 
equal to about 1092 [1310] seconds, or about 18.2 [21.8] minutes. If you need 
to specify a time interval of 18.2 [21.8] minutes or less, place a zero in the hi 
argument, and the number of ticks in the /o argument to the .TIMIO macro. 

If you need to specify a time interval longer than 18.2 [21.8] minutes, think 
of the high-order word as a carry word. Each interval of 18.2 [21.8] minutes' 
duration causes a carry of 1 into the high-order word. So, to specify an inter- 
val shghtly greater than 18.2 [21.8] minutes, supply a 1 to the hi argument, 
and a to the to argument. To specify 36.4 [43.6] minutes, move 2 to the hi 
argument, to the lo argument , and so on. Since the two-word time permits 
you to indicate up to 65565 units of 18.2 [21.8] minutes each, the largest 
time interval you can specify is about 2.3 [2.7] years. 

The only words of information you must set up yourself in the timer block 
are the job number, the sequence number, and the address of the comple- 
tion routine. You can get the job number from the current queue element, 
and then move it to the timer block. You assign the sequence number 
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yourself. Start with 177400 and work up to the highest valid sequence 
number, 177477. The job number and sequence number are passed to the 
completion routine when it is entered. You must move the address of the 
completion routine to the seventh word of the timer block in a position- 
independent manner. 

The .TIMIO macro expands as follows: 

.TIMIOtbk,hi,lo 

JSR R5,@$TIMIT ;POINTER AT END OF HANDLER 

.WORD tbk -. 



.WORD 

.WORD hi 

.WORD lo 



CODE FOR .TIMIO 

HI ORDER TIME INTERVAL 

LO ORDER TIME INTERVAL 



7.6.2 .CTIMIO Macro 

When the condition the handler was waiting for occurs, you should issue a 
cancel time-out call, which disables the completion routine. Use the 
.CTIMIO macro call in your handler to cancel the time-out request. Execu- 
tion must be in system state when you issue the call. Be sure to issue a 
.FORK call first if you use .CTIMIO at interrupt level. 

For example, a line printer handler could check for an off-line condition. 
When a program requests an I/O transfer, the handler's I/O initiation sec- 
tion forces an immediate interrupt. The handler's interrupt service section 
then checks the device error bit. If the bit is set, the printer is not on Une 
and the handler prints a message, sets a two-minute timer with .TIMIO, 
and returns to the monitor with an RTS PC instruction to wait for another 
interrupt. The device should not interrupt again until the error condition 
has been fixed by an operator. If no interrupt occurs within two minutes, 
the timer completion routine prints another error message, sets another 
two-minute timer, and returns again to the monitor with RTS PC to wait for 
an interrupt. (See Figure 7-3 for the Une printer handler example.) 

In this example, when an interrupt finally occurs and the error bit is clear, 
the handler issues the .CTIMIO call to cancel the timed wait. 

As another example, a disk handler could set a timer before it starts up a 
seek operation. Since seeks interrupt twice, the handler should not cancel 
the timer after the first interrupt. When the second interrupt occurs, 
though, the seek is complete, and the handler should then cancel the timer. 

If the time interval in any appUcation has already elapsed and the device 
has, therefore, timed out, the .CTIMIO request fails. Because the comple- 
tion routine has already been placed in the queue, the ,CTIMIO call returns 
with the carry bit set. You can usually ignore this condition. 

The format of the .CTIMIO macro call is as follows: 

.CTIMIO tbk 

tbk is the address of the seven-word timer block described above. Note that 
this time block you specify in the .CTIMIO call must be the same one 
already used by the corresponding .TIMIO request. 
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The .CTIMIO macro expands as follows: 

.CTIMIO 



JSR 


R5,@i 


tTIMIT 


;POINTER AT END OF HANDLER 


.WORD 


tbk - 






.WORD 


1 




;CODE FOR .CTIMIO 



Note that if a job aborts and your handler is entered at its abort entry point, 
you must immediately cancel any outstanding timer requests. However, if a 
timer completion routine has already been entered, you must wait for it to 
execute. 

7.6.3 Device Time-out Appiications 

Device time-out support is used by RT-11 in only a few instances. However, 
ther(} are a number of conditions in which timer requests are appropriate. If 
you are writing a handler for ^i^our own device, consider the following sec- 
tions to determine whether or not timer requests would be useful to you. 

7.6.3.1 Multi-terminal Service ~ The resident multi-terminal service in 
RT-11 that supports DZll and DZVll modems uses device time-out to 
checlk the status of remote dial-up lines. The bootstrap starts up a polUng 
routine to check each modem for a change in status. If a change occurs, the 
terminal service takes the appropriate action: it either recognizes a new line, 
or disconnects a line when carrier is lost. The last instruction in the polling 
routine issues a .TIM 10 call to start a half-second timer. The timer comple- 
tion routine restarts the polling routine after a half-second elapses. 

7.6.3.2 Typical Timer Procedure for a DIsIc Handler — A disk handler could im- 
plement a timer procedure for any disk operation. The purpose of the timer 
routine is to cancel or restart any operation that takes too long. If an opera- 
tion does not complete within a reasonable amount of time, chances are 
good that a disk error of some sort corrupted the operation. 

The handler's I/O initiation section sets a timer by using the .TIMIO call. 
Then the handler starts up the operation that a job requested: a read, write, 
or seek operation. The handler returns to the monitor with an RTS PC in- 
struction and waits for a device interrupt. 

If an interrupt occurs before the time limit expires, the handler cancels the 
timer and performs its normal sequence of error checking on the results of 
the transfer. In general, the handler either drops to fork level to restart an 
incorrect operation, or exits to the monitor with .DRFIN to remove the cur- 
rent queue element. 

If an interrupt does not occur within the time limit, the timer completion 
routine begins to execute. Its first action should be to simulate an inter- 
rupt. This action dupMcates the handler environment after a genuine inter- 
rupt and makes sure that the st;ack has the necessary information. Then the 
timer completion routine acts as though the device interrupted but the 
transfer was in error. The timer completion routine simply branches to the 
correct section of code in the interrupt service section of the device handler 
to finish the processing. 
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The timer completion routine should use the following instructions to 
simulate an interrupt and enter system state: 



MOV 


@SP,-(SP) 


;MAKE ROOM ON THE STACK 


CLR 


2(SP) 


;FAKE INTERRUPT PS = 


.MIPS 


#340 


;G0 TO PRIORITY 7 


.INTEN 


O.PIC 


; ENTER SYSTEM STATE 



After the handler enters system state, it takes the appropriate action as a 
result of the time-out. The handler can try the operation again. To do this, it 
decrements the retry count, drops to fork level, and branches to the I/O ini- 
tiation section. The code in the initiation section sets another timer, 
restarts the transfer, and returns to the monitor with an RTS PC instruc- 
tion to await another interrupt. 

If the handler decides that the time-out indicates a serious error, one that 
should not be retried, this same procedure can be followed for a transfer 
whose retry count is used up. In this case, the handler sets the hard error 
bit in the Channel Status Word and then exits to the monitor with the 
.DRFIN call to remove the current queue element. 

NOTE 

Before a handler goes through the .DRFIN routine to 
remove the current queue element, it must cancel any timer 
request that has not yet expired. 

7.6.3.3 Line Printer Handler Example — The extended example shown in 
Figure 7-3 consists of excerpts from a version of the RT-11 Mne printer 
handler modified to use timer support to check for the device off-line 
condition. 

When the handler's I/O initiation section starts up a transfer, it forces an 
immediate interrupt, which causes the handler's interrupt service section to 
check the error bit in the CSR. If there is an error, control passes to the 
routine OFFLIN, which issues a .SYNCH call to enter user state, prints an 
error message on the console terminal, and then sets a two-minute timer. 
The handler then returns to the monitor with an RTS PC instruction and 
waits for the device to interrupt. 

If the device interrupts, it means that the error condition has been cor- 
rected by an operator. The handler cancels the timer and checks the error 
bit once again to make sure there are no problems. If there is no error, the 
handler proceeds as usual. If there is an error, the handler loops back to the 
OFFLIN routine. If an interrupt does not occur within two minutes, the 
timer completion routine begins to execute. It prints an error message, sets 
another two-minute timer, and returns to the monitor with an RTS PC in- 
struction to await an interrupt. 
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Figure 7-3: Line Printer Handler Example 



I/O INITIATION SECTION 



RET J 



.riRBEG 


LP 


MOV 


LF'CQE,R4 


ASL 


6<R4) 


BCC 


LPERR 


BEQ 


LPDONE 


BIS 


♦lOOreLPS 


RTS 


PC 



)RA POINTS TO CURRENT Q ENTRY 

JUORD COUNT TO BYTE COUNT 

JA READ REQUEST IS ILLEGAL 

F SEEKS COMPLETE IMMEDIATELY 

;CAUSE AN INTERRUPT f STARTING TRANSFER 



i INTERRUPT SERVICE SECTION 
•ENABL LSB 





• IIRAST 


LP>4r LPDONE 




TST 


TICMPL 




BEQ 


1» 




.CTIMIO 


TIMBLK 




BCS 


1» 




CLR 


TICMPL 


l$t 


MOM 


LPCQE,R4 




TST 


e(PC)+ 


LPS! 


.UORD 


LPtCSR 


ERROPT! 


EMI 


OFFLIN 



;iS A TIMER ELEMENT ACTIVE? 

>H0 

iYESj CANCEL IT 

fERROR 

SAND DON'T DO IT AGAIN 

!R4 POINTS TO CURRENT QUEUE ELEMENT 

(ERROR CONDITION? 

(LINE PRINTER STATUS REGISTER 

JYESj HANG TILL CORRECTED 



I/O COMPLETION SECTION 



LPDONE: CLR SLPS 
.DRFIN LP 



JTURN OFF INTERRUPT 



PRINTER OFF LINE. PRINT WARNING EVERY 2 MINUTES 



offlin: 


MOV 


LPCQEfRS 




MOVB 


QtJNUM(RS>,R5 




ASR 


R5 




ASR 


R5 




ASR 


R5 




BIC 


♦"C<16>.R5 




MOV 


RSfSYJNUM 




MOV 


RSjTIJNUM 




•SYNCH 


SYNBLKrPIC 




RTS 


PC 


i*t 


CLR 


TICMPL 




TST 


BLPS 




BPL 


2» 




MOV 


PC.RO 




ADD 


♦MESSAG-.rRO 




.PRINT 






MOV 


PCfRO 




ADD 


*1»-. .RO 




MOV 


ROrTICMPL 




.TIMIO 


TIMBLKt0.2*60 


2$: 


RTS 


PC 


TIMBLKJ 


.WORD 







. WORD 







.WORD 





TIJNUM! 


.WORD 







• WORD 


177400 



JPOINT TO QUEUE ELEMENT 

(GET JOB NUMBER OF CURRENT JOB 

iSHIFT IT 

! RIGHT 

} 3 BITS 

(ISOLATE JOB NUMBER 

(SAVE IT FOR .SYNCH 

(SAVE IT FOR .TIMIO 

(GO TO USER STATE 

(SYNCH FAILED. PUNT 

(INDICATE THAT WE GOT HERE 
(IS THERE STILL AN ERROR? 
(NO. QUIT 

(AS COMPLETION ROUTINE. PRINT MESSAGE 
(POINT TO MESSAGE AS PIC 
(PRINT IT 
(IN A PIC WAY. 

( POINT TO TIMIO COMPLETION ROUTINE 
(SAVE IT 
.*^,0. (SET A 2-MINUTE TIMER 
(RETURN LATER 

(TIMER BLOCK! HI ORDER TIME 

(LO ORDER TIME 

(LINK 

(JOB NUMBER 

(SEQUENCE NUMBER 
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Figure 7-3: Line Printer Handler Example (Cont.) 





.WORD 


fMONITOR PUTS -i HERE 


TICMPL) 


.UORD 


JAIiriRESS OF COMPLETION ROUTINE 


synblk: 


.UORD 


JSYNCH BLOCK 


SYJNUM! 


.UORD 


fJOB NUMBER 




.UORD 


0,0,0,-1,0 (OTHER 


MESSA6: 


.ASCIZ 
.EVEN 


"TLP-U-LP off line - please correct* 




.DREND 


LP 



7.7 Error Logging 



Error logging is an optional feature of RT-11 designed to help you monitor 
the reliability of your system. Device handlers that include support for er- 
ror logging call the error logger after each I/O transfer. The error logger 
creates a historical record of the device's I/O activity that you can use to 
check its reliability. 

You must perform a system generation to select error logging. Error log- 
ging can run in either the FB or XM environment. If your system has the 
capability to run system jobs, the error logger runs as a system job; other- 
wise, the error logger can run as an ordinary foreground job. The system 
generation conditionals for error logging are as follows: 

ERL$G If this value = 1, it indicates that error logging is enabled 

for this system. 

ERL$U This represents the maximum number of individual device 

units for which the error logger collects statistics. The 
default value is 10, and the absolute maximum number is 
30. Each unit adds seven words to the error logger. One 
slot is required for each unit. (For example, two slots are re- 
quired for a system with an RK05 with two units.) Your 
response to a system generation dialogue question 
establishes the value of this variable. 

You should consider your time and memory requirements before deciding to 
use error logging because error logging creates a certain minimal amount of 
overhead for each I/O transfer, and the error logger itself uses almost 2K 
words of memory. However, the error logger does not have to run constant- 
ly, so that the memory it requires can be made available to your programs 
when necessary, and calls that your handler makes to the error logger 
return immediately. The most convenient way to use the error logging 
system is as a check when you suspect device reliability problems, which 
means using it only when necessary. 

The following sections describe how to implement error logging in your 
device handler and what information you should log. They also show you 
how to add headings for your device to the error reporting program. See the 
RT-11 System User's Guide for more information on the entire error log- 
ging system and how to use it. 

All code in your handler that applies strictly to error logging should be 
placed inside conditional assembly directives. These directives include the 
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error logging code if the symbol ERL$G is 1, and omit it otherwise. This 
way, the system parameters select whether or not the error logging code is 
included in the handler each time you assemble it. 



7.7.1 When and How to Call the Error Logger 

A hemdler calls the error logger after each I/O transfer, whether the transfer 
was successful or not. If the transfer was in error, the handler calls the error 
logger once for each retry of the transfer, and once again when the allotted 
number of retries has been exhausted. 

Since calls to the error logger must be serialized, the handler can issue them 
only during I/O initiation or following a .FORK call. 

The handler must set up registers before it issues the call to the error log- 
ger. The register assignments for the three kinds of calls are described in 
the following sections. 

7.7.1.1 To Log a Successful Transfer — Set up R4 and R5 as described below 
before calling the error logger after each successful transfer. 

R5 must point to the third word of the current queue element. 

R4 contains two bytes of information: the high byte is the device- 
identifier byte, dd%COD; the low byte is - 1. 

7.7.1.2 To Log a Hard Error — Set up R2 through R5 as described below 
before calling the error logger after a hard error has occurred. Generally, 
hard errors are those that are not recoverable. Examples of hard errors are 
device off Une or not powered up, device write-locked, no tape in paper tape 
readers, and so forth. A soft eri-or that has exhausted its allotted number of 
retries is considered a hard error. 

R5 must point to the third word of the current queue element. 

R4 contains two bytes of information: the high byte is the device iden- 
tifier byte, dd$COD; the low byte is 0. 

R3 contains two bytes of information: the high byte contains the total 
number of retries allotted for this transfer; the low byte contains 
the number of device registers whose contents should appear in the 
error report. 

R2 is a pointer to a buffeir in the handler that contains the device 
registers to be logged. 

7.7.1.3 To Log a Soft Error— !3et up R2 through R5 as described below 
before calling the error logger after a soft error has occurred. Generally, soft 
errors are those that are recoverable and can possibly be corrected by retry- 
ing the transfer. Examples of soft errors include timing errors and hard- 
ware read or write errors. 

Initialize a counter in your handler with the total number of retries allotted 
for each transfer. Decrement the count as each retry for a soft error is per- 
formed. When the count reaches zero, the error logger considers the error to 
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be a hard error. On soft error, the error report prints a separate entry for 
each retry of a given transfer. 

All retries are printed in the report even if the registers are identical. The 
report does not distinguish between hard or soft immediate errors. It prints 
only the contents of the registers at the time of the error and the value of 
the retry count. An immediate hard error can be recognized in the output 
since it will appear with a retry count of with no immediately previous er- 
rors on that device and unit (with a retry count greater than 0). 

R5 must point to the third word of the current queue element. 

R4 contains two bytes of information: the high byte is the device iden- 
tifier byte, dd$COD; the low byte is the current value of the retry 
counter. (This value should decrease with each retry until it reaches 
0, at which point the error is considered a hard error.) 

R3 contains two bytes of information: the high byte contains the total 
number of retries allotted for this transfer; the low byte contains 
the number of device registers whose contents should appear in the 
error report. 

R2 is a pointer to a buffer in the handler that contains the device 
registers to be logged. 

7.7.1.4 Differences Between Hard and Soft Errors — The error logger itself 
does not differentiate between hard and soft errors and records the same in- 
formation in both cases. However, by examining the report, you can deter- 
mine if a hard error occurred, because a transfer that has exhausted all of its 
retries will have records in the report for each of these retries, including one 
with a retry count of 0. It is therefore up to you to interpret the error. 

In some circumstances, user-correctable errors, such as device off Une or 
write-locked, should not call the error logger. Usually disk and tape hard- 
ware errors are the only ones reported, since these are the errors you are 
concerned about on the level of device reliability. 

7.7.1.5 To Call the Error Logger — Once the required registers are set up, call 
the error logger as follows: 



JSR 



PC,@$ELPTR 



$ELPTR is a pointer into the Resident Monitor. The .DREND macro 
allocates space in the handler for this pointer. The pointer is filled in at 
bootstrap time (for the system device) or at .FETCH or LOAD time (for a 
data device). If the error logger is not running, the monitor returns im- 
mediately to the handler. If the error logger is running, a link word in 
RMON contains its entry point. The following lines of code from RMON 
show how the call to the error logger is accomplished. 



$ERLOG: MOV (PC) + ,-{SP) 
$ELHND:: .WORD 



ENTER HERE FROM HANDLER 
PUSH NEXT WORD ON STACK 
IF ERROR LOGGER NOT RUNNING; 
ELSE CONTAINS ERROR 
LOGGER ENTRY POINT 
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BNE 1$ 
TST (SP) + 
1$: RTS PC 



BRANCH IF LOADED 
PURGE STACK 

INVOKES ERROR LOGGER OR 
RETURNS TO HANDLER 



The SRUN or FRUN command fills in the error logger entry point; the 
UNIiOAD EL command zeroes $ELHND. 

On return from the error logger call, RO through R3 are restored in your 
handler, and R4 and R5 are desstroyed. 



7.7.2 Error Logging Examples 

See the handler listings in Apjaendix A for examples of error logging. 

7.7.3 How to Add a Device to tlie Reporting Program 

After you implement error logging in your device handler, the next step is 
to modify the reporting system so that the name of your device will appear 
in the report headings and th<} registers will be printed properly. The file 
ERRTXT.MAC contains the information for report headings for the 
devices supported by the RT-ll error logging reporting utility ERROUT. 
To include your device, simply edit this file, reassemble it, and rehnk it. 

Use the following commands to reassemble and relink ERRTXT: 

MACRO/LIST ERRTXT 
LINK ERROUT.ERRTXT 

ELBLDR Macro 

Use the ELBLDR macro to add a new device to the error log reporting 
system. Edit the file ERRTXT.MAC to add the ELBLDR macro call for 
your device. The format of the call is as follows: 

ELBLDR xx,< type>,C1,C2,< C3> 

XX is the device-identifier byte, dd$COD, that you specified in the .DRDEF 
macro. It must be a value between and 377 octal. 

type is any ASCII string you want to print on the report as the device type. 
It can be up to 59 characters long. Remember to enclose it in angle 
brackets. 

CI is one of the two strings DISK or TAPE. It identifies the device general 
classification. 

C2 is the two-character device name. You must specify exactly two 
characters. 

C3 isi a Ust of device register mnemonics (minus the first two characters) 
representing the registers that the handler logs. Separate the mnemonics 
with commas; remember to use the angle brackets (<>). 

Assembly errors result if you do not specify the parameters to ELBLDR 
correctly. 
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None of the parameters for the ELBLDR call is optional. 

For example, the ELBLDR call for the RK handler is as follows: 

ELBLDR 0,<RK11/RK05>, DISK,RK,<DS,ER,CS,WC,BA,DA,DB> 

This example shows that the device is the RK11/RK05 disk, its two- 
character name is RK, its device-identifier byte is 0, and the registers its 
handler logs are RKDS, RKER, RKCS, RKWC, RKBA, RKDA, and 
RKDB. 

The default input file name for ERROUT is ERRLOG.DAT. This is also the 
default output file for EL itself. However, you can save previous 
ERRLOG.DAT files by renaming or copying them. Thus, ERROUT can 
operate on any file with the same format as ERRLOG.DAT. The name is 
not important; the format is. The internal format of the data in this file is 
documented in Chapter 8 of this manual. 



7.8 Special Functions 



Sometimes handlers need to perform device-specific actions for which there 
are no corresponding RT-11 programmed requests. Examples of these ac- 
tions include rewinding magtapes and reading or writing absolute sectors 
on diskettes. The .SPFUN programmed request provides a means for pro- 
grams to initiate such special functions. When a program issues a .SPFUN 
request, it supphes a special function code as one of the arguments. This 
code tells the handler which special function it is to perform. For example, 
the code that tells the MT handler to perform an off-line rewind is 372. 



7.8.1 .SPFUN Programmed Request 

The format of the .SPFUN programmed request is as follows: 
.SPFUN area,chan,func,buf,wcnt,blk[,crtn] 

For a complete description of the arguments for .SPFUN programmed re- 
quest, see the RT-11 Programmer's Reference Manual. 

To use special function calls in your handler, you define the interface be- 
tween the programmed request and the device handler. Thus, the meanings 
of the buf, went, and blk arguments depend on the particular special func- 
tion the request invokes. Of course, if the request calls for a data transfer, 
the arguments have their usual meanings. Note, however, that although the 
monitor checks to make sure that buf is a valid address within the job area, 
it does not make sure that buf plus went is still within the job area. It is 
therefore your responsibility to specify valid values if you use the .SPFUN 
request to transfer data. 

If the special function call is to return a single value, buf should be a one- 
word buffer area. You are free to interpret went and blk as anything you 
choose. They can be specification words of some sort, pointers to more buf- 
fers, and so on, as long as the handler interprets them according to the 
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special function code. Note that the monitor does not alter these values in 
any way when it passes them to the handler. For example, it does not 
change the word count from positive to negative. 

7.8.2 How to Support Special Functions in a Device Handler 

To implement support for special function calls in your handler, you must 
specify SPFUN$ as one of the bits in the stat value you provide to the 
.DRDEF macro. This indicates that the handler can accept special 
functions. 

Next, define symboUcs in the handler to represent the types of special func- 
tions the handler can perform. For example, the DY diskette handler 
defines the following special function codes: 



SIZ$FN = 373 

WDD$FN = 375 

WRT$FN = 376 

RED$FN = 377 



GET DEVICE SIZE 

WRITE WITH DELETED DATA MARK 
WRITE ABSOLUTE SECTOR 
READ ABSOLUTE SECTOR 



Note that all special function codes must be negative byte values (that is, 
they must be in the range 200 through 377 octal). Consult the RT-11 Pro- 
grammer's Reference Manual for a complete Ust of RT-11 codes. For the 
sake of consistency across devices, it is advisable to have each special func- 
tion code repesent the same operation on all devices. So, check the RT-11 
Programmer's Reference Manual first to see if a code for your function 
already exists, and use it if it does. If there is no existing code for your par- 
ticular function, assign codes starting with 200 and work toward 377 from 
there. This poUcy should avoid conflicts with new RT-11 codes in the 
future. 

When the handler is entered for an I/O transfer, it should check the fourth 
word of the queue element to S(Be if this is a request for a special function. 
Q.FUNC, which is the low byte of the fourth word of the I/O queue element, 
contains the special function code. On standard I/O requests for read, write, 
and seek operations, this byte iis 0. For special function calls, this value is 
the negative special function code. Be sure to check that the code is valid 
for your device and if it is not, return a hard error immediately. 

If this is a request for a special function, the handler should initiate that 
function and return with an RTS PC instruction. In the interrupt service 
section the handler should, as usual, check for errors and determine whether 
the operation is complete. Th<} handler returns either data or words of 
status information to the calling program in the user buffer. 

Since you are implementing the special functions for a particular device, 
you can establish the caUing convention for that function in the .SPFUN 
programmed request as well as the return convention from the handler. Be 
sure the handler treats the arguments appropriately for each different 
special function call. 

For a good example of a handler that implements special functions, see the 
DX handler in Appendix A. 
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7.8.3 Variable Size Voiumes 

A handler can control a device that permits volumes with two or more dif- 
ferent sizes to be used. Examples of such handlers are the DM handler — 
which can service both RK06 and RK07 disks through a single controller — 
and the DY handler — which can service either a single-density or a double- 
density diskette in a single device unit. 

A handler for a device that supports volumes of different sizes should pass 
the size, in blocks, of the smallest volume in the size parameter of the 
.DRDEF macro. This is the value that is returned to a running program 
when it issues the .DSTATUS programmed request. 

If it is important that a running program know the size of the volume that 
is currently mounted, the program can do a .SPFUN call. The handler must 
be able to respond to the request by returning the actual volume size in a 
one-word buffer area. The handler should also implement support for 
special functions, as described above. The standard special function code 
for determining the actual volume size is 373. 

DUP requires modification to correctly initialize and squeeze a device that 
supports variable size volumes. See the RT-11 System Release Notes. 

7.8.4 Bad Biocic Replacement 

If your handler is to support bad block replacement, you must implement 
special function codes 377, 376, and 374, as they are implemented for the 
DL handler. See the description of the RLOl device in Chapter 10 for more 
information. 

DUP requires modification to correctly initialize and squeeze a device that 
supports bad block replacement. See the RT-11 System Release Notes. 

7.8.5 Devices with Special Directories 

The RT-11 monitor can interface to file-structured devices having nonstan- 
dard (that is, non-RT-11) directories. Examples of special devices are 
magtape and cassette. Their handlers set bit 12 (SPECL$) of the device 
status word. The USR processes directory operations for RT-11 directory- 
structured devices; for special devices, the handler must process directory 
operations such as .LOOKUP, .ENTER, .CLOSE, and .DELETE, as well as 
data transfers. 

The monitor requests a special directory operation by placing a positive, 
nonzero value in the function code byte of the queue element. The positive 
function codes are standard for all devices. They are as follows: 

Code: 12 3 4 

Function: Close Delete Lookup Enter 

These functions correspond to the programmed requests .CLOSE, 
.DELETE, .LOOKUP, and .ENTER, which are described in the RT-11 Pro- 
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grammer's Reference Manual. The .RENAME request is not supported for 
special devices. 

In a (jueue element for a special directory operation, word 5 of the queue ele- 
ment contains a pointer to the file descriptor block containing the device 
name, file name, and file type in Radix-50. 

Software errors (such as file not found, or directory full) occurring in special 
device handler during directory operations are returned to the monitor. A 
unique error code is chosen for each type of error. The error code is directly 
returned by placing it in SPUSR (special device USR error), located at fixed 
offset 272 from the start of the Resident Monitor. Hardware errors are 
returned in the usual manner by setting bit in the Channel Status Word 
pointed to by the second word of the queue element. 

Programmed requests for direc;tory operations to special devices are han- 
dled by the standard programmed requests. When a .LOOKUP is issued, 
for example, the monitor checks the device status word for the special 
device bit. If the device has a sipecial directory structure, the proper func- 
tion code is inserted into the queue element and the element is directly 
queued to the handler, by-passing any processing by the USR. Device in- 
dependence is maintained, since .LOOKUP, .ENTER, .CLOSE, and 
.DELETE operations are transparent to the user. 

7.9 Device Handlers in XIVI Systems 

Device handlers for S J and FB environments require a few changes to work 
properly in an XM system. Before describing the environment for a handler 
in an XM system, the following sections outline the nomenclature conven- 
tions. The final sections explain how a handler communicates with a user 
buffer in extended memory. 

7.9.1 Naming Conventions and the System Conditionai 

When you write a device handler, write a common source file called 
dd.MAC, where dd is the two-character device name, enclosing the code that 
pertains to extended memory support in conditional assembly directives. 
The system generation conditional that represents extended memory sup- 
port is MMG$T, which has a value of if extended memory support is not 
select;ed and of 1 if extended memory support is selected. This means that 
the extended memory code is only assembled when the value of the condi- 
tional MMG$T is 1. Assemble your source file with the system conditional 
file, SYCND, and with XM.MAC, producing ddX.OBJ for XM systems, or 
dd.OBJ for SJ and FB systems. This procedure ensures that the system 
generation features that the handler supports match those of the current 
monitor. 

7.9.2 Xi\A Environment 

In an XM system, handlers must reside within the lower 28K words of 
physical memory, but not within the area of physical memory mapped by 
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PARI, an area that includes the memory locations between 20000 and 
37776. In a system that uses the MQ handler to communicate between 
system jobs, handlers must also not be located in the area mapped by 
PAR2, the memory locations between 40000 and 57777. Before you run pro- 
grams that use handlers, you must make them resident with the LOAD 
monitor command, which enforces the address restriction. 

When handlers are entered, they run with kernel mapping, which permits 
access to the lower 28K words of memory plus the device I/O page (see 
Chapter 6). The program that requests the I/O transfer, however, need not 
have the same mapping as kernel mapping. In fact, the program can fall in- 
to one of three valid categories: 

• A privileged job whose mapping is identical to kernel mapping 

• A privileged job that maps to physical memory addresses above 28K 
words 

• A virtual job with any kind of mapping 

As you may suspect, the chief difficulty for handlers in XM systems is com- 
municating with the user data buffer. This difficulty arises from the fact 
that the program requesting an I/O transfer suppUes a 16-bit virtual buffer 
address in the programmed request, although that portion of the user's vir- 
tual addressing space may be mapped somewhere else in physical memory. 
The handler must therefore find the actual 18-bit physical address of the 
user data buffer before moving information to it or from it. The monitor 
verifies that the user buffer area occupies contiguous locations in physical 
memory. 

The fact that in an XM system, locations in physical memory are expressed 
as 18-bit addresses, is important when you need to specify an address 
within the handler itself as a buffer address. If, for example, the handler 
contains a string of zeroes that it writes to a device as part of initiaUzation, 
the handler sets up the device write operation, specifying the address of the 
string in the handler as the buffer address. Since the handler is located 
within the lower 28K words of physical memory, its physical address can be 
expressed as its virtual 16-bit address plus two extra bits for XM, bits 16 
and 17 of the 18-bit address, which must be 0. 

Figure 7-4 illustrates an XM system. The program that requests an I/O 
transfer has mapped its data buffer area into physical memory above the 
28K word boundary. 

The RT-11 monitor provides routines for handlers to use to access the real 
user data buffer in physical memory. The following sections describe these 
routines and the situations in which they are useful. 

7.9.3 The Queue Element in XM 

In order to locate the actual user buffer in physical memory, the handler re- 
quires an extra word of information in the queue element. This word is a 
value for PARI that, when combined with the user virtual buffer address. 
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Figuire 7-4: Device Handler in XM 
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provides the physical address of the buffer. Although only one extra word is 
used for XM handlers, the queue element allows room for two words in addi- 
tion to that. These two words, at offsets 20 and 22, are reserved for future 
use l:>y DIGITAL and should not be used. 

When the system conditional MMG$T is set to 1, the .QELDF macro invok- 
ed by .DRDEF in the beginnhig of your handler expands to generate the 
correct offsets for the XM queue element. The macro expansion is as 
follows: 



Q.LINK = 
Q.CSW = 2. 
Q.BLKN=4. 
Q.FUNC = 6. 
Q.JNUM=7. 
Q.UNIT = 7. 
Q.BUFF = -O10 
Q.WCNT = -012 
Q.C0MP = '014 
Q$LINK= -4 
Q$CSW = 2 
Q$BLKN=0 
Q$FUNC = 2 
Q$JNUM=3 
Q$UNIT = 3 
Q$BUFF = 4 
Q$WCNT=6 
Q$COMP=-O10 
Q.PAR = '016 
Q$PAR = -012 
Q.ELGH=-024 



(Link to next queue element) 
(Pointer to channel status word) 
(Physical block number) 
(Special function code) 
(Job number) 
(Device unit number) 
(User virtual buffer address) 
(Word count) 

(Comipletlon routine code) 
(Symbols for easy reference:) 



(PARI value) 

(Lenjjth of queue element) 
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7.9.4 DMA Devices: $MPPHY Routine 

DMA devices — most disks, for example — usually work with 18-bit ad- 
dresses so that their handlers need not map to the user buffer. These 
handlers use the monitor routine $MPPHY to find the user buffer in 
physical memory. $MPPHY uses the Q.PAR value from the queue element 
and the Q.BUFF virtual buffer address to create the correct 18-bit address 
for the user buffer. 

The format of the call for the $MPPHY routine is as follows: 

JSR PC,@$MPPTR 

$MPPTR contains a pointer to the $MPPHY routine in the Resident 
Monitor. The .DREND macro allocates space for this pointer at the end of 
the handler. The pointer is filled in at bootstrap time (for the system device) 
or at LOAD time (for a data device). 

Before the call: 

R5 must point to Q.BUFF, the fifth word in the queue element. 

After the call: 

(SP), the first word on the stack, contains the low-order 16 bits of the 
physical buffer address. 

2(SP), the second word on the stack, contains the high-order two bits of the 
physical buffer address in bit positions 4 and 5. 

R6 points to Q.WCNT, the sixth word in the queue element. The value is not 
changed. 

The following example is from the RK handler. 



CMP 


(R5) + ,-(R4) 


ADVANCE TO BUFFER ADDRESS IN 
QUEUE ELEMENT 


JSR 


PG,@$MPPTR 


CONVERT USER VIRTUAL ADDRESS 
TO PHYSICAL 


MOV 


(SP) + ,-(R4) 


PUT LOW 16 BITS IN RKBA, 
HIGH BITS ON STACK 


MOV 


(R5) + ,-(R4) 


PUT WORD COUNT INTO RKWC 


BEQ 


7$ 


COUNT = SEEK 


BMI 


5$ 


NEGATIVE = WRITE, SO 
ALL SET UP 


NEG 


@R4 


POSITIVE = READ, 

FIX COUNT FOR CONTROLLER 


MOV 


#GSIE!FNREAD!GSG0,R3 


FUNCTION IS READ 


BIS 


(SP) + ,R3 


MERGE HIGH ORDER ADDRESS 
BITS INTO FUNCTION 


MOV 


R3,-(R4) 


START THE OPERATION 


RTS 


PC 


AWAIT INTERRUPT 



5$: 



7.9.5 Chiaracter Devices: $GETBYT and $PUTBYT Routines 

The handlers for character-oriented devices, such as paper tape and line 
printers, must transfer the data from the device to the user buffer area 
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themselves. The device itself uses registers in the I/O page to store one 
character at a time. The handler can use two monitor routines — $GETBYT 
and $PUTBYT — to move data between the I/O page and the user buffer 
aregi. 

7.9.5.1 $GETBYT Routine— A handler can use the $GETBYT monitor 
routine to move a byte from the user buffer in physical memory to the 
stack. The handler can then move the character into the device data buffer 
register in the I/O page and initiate an I/O transfer. 

The format of the call for the $GETBYT routine is as follows: 

JSR PC,@$GTBYT 

$GTBYT contains a pointer to the $GETBYT routine in the Resident 
Monitor. The .DREND macro allocates space for this pointer at the end of 
the handler. The pointer is filksd in at bootstrap time (for the system device) 
or at LOAD time (for a data device). 

Before the call: 

R4 must point to Q.BLKN, thie third word in the queue element. 

After the call: 

(SP), the first word on the stack, contains the next byte from the user buffer 
in the low byte. The contents of the high byte are not defined. 

R4 is unchanged. 

The buffer address (Q.BUFF) in the queue element is updated by 1. If a 
mapping overflow occurs, the monitor routine subtracts 20000 from the 
value in Q.BUFF and adds 200 to the value in Q.PAR. Mapping overflow is 
described in more detail in Section 7.9.7. 

The following example from the PC handler shows how the handler gets a 
byte from the user buffer and punches it on paper tape. 

R4 POINTS TO Q.BLKN 

ERROR? 

PUNCH OUT OF PAPER 

ANY MORE CHARACTERS TO OUTPUT? 

NO — TRANSFER DONE 

DECREMENT BYTE COUNT 

(IT IS NEGATIVE) 

GET A BYTE FROM USER BUFFER 

PUNCH IT 

7.9.5.2 $PUTBYT Routine — After a successful data transfer, a handler can 
get a character from the device data buffer register in the I/O page and push 
it onto the stack. It can then use the $PUTBYT monitor routine to move a 
byte from the stack to the user buffer in physical memory. 

The format of the call for the $PUTBYT routine is as follows: 

JSR PC,@$PTBYT 
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MOV 


PRCQE,R4 


TST 


@#PP$CSR 


BMI 


PPERR 


TST 


Q$WCNT(R4) 


BEG 


PRDONE 


INC 


Q$WCNT(R4) 


JSR 


PC,@$GTBYT 


Move 


(SP) + ,@#PPB 



$PTBYT contains a pointer to the $PUTBYT routine in the Resident 
Monitor. The .DREND macro allocates space for this pointer at the end of 
the handler. The pointer is filled in at bootstrap time (for the system device) 
or at LOAD time (for a data device). 

Before the call: 

i?4 must point to Q.BLKN, the third word in the queue element. 

The byte to transfer to the user buffer must be on the top of the stack. The 
character must be in the low byte of the stack's first word. The high byte is 
unpredictable. 

After the call: 

The word containing the character to transfer is removed from the stack. 

R4 is unchanged. 

The buffer address (Q.BUFF) in the queue element is updated by 1. If a 
mapping overflow occurs, the monitor routine subtracts 20000 from the 
value in Q.BUFF and adds 200 to the value in Q.PAR. Mapping overflow is 
described in more detail in Section 7.9.7. 

The following example from the PC handler shows how the handler gets a 
character from the paper tape reader and moves it to the user buffer. 



MOV PRCQE,R4 

MOVB @#PRB,-(SP) 

JSR PC,@$PTBYT 

DEC Q$WCNT(R4) 



R4 POINTS TO Q.BLKN 
GET A CHARACTER 
MOVE IT TO USER BUFFER 
DECREASE BYTE COUNT 



7.9.6 Any Device: $PUTWRD Routine 

The monitor routine, $PUTWRD, is similar to $PUTBYT, except that 
$PUTWRD moves a word to the user buffer in physical memory instead of 
a byte. This routine is useful when the handler needs to transfer a word of 
status information to the user buffer, rather than a data character from a 
device. Handlers for any kind of device can use $PUTWRD. 

The format of the call for the $PUTWRD routine is as foUows: 

JSR PC,@$PTWRD 

$PTWRD contains a pointer to the $PUTWRD routine in the Resident 
Monitor. The .DREND macro allocates space for this pointer at the end of 
the handler. The pointer is filled in at bootstrap time (for the system device) 
or at LOAD time (for a data device). 

Before the caU: 

R4 must point to Q.BLKN in the queue element. 

The word to transfer to the user buffer must be on the top of the stack. 
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After the call: 

Thf! word to transfer is removed from the stack, 

R4 is unchanged. 

The buffer address (Q.BUFF) in the queue element is updated by 2. If a 
mapping overflow occurs, the monitor routine subtracts 20000 from the 
value in Q.BUFF and adds 200 to the value in Q.PAR. Mapping overflow is 
described in more detail in Stsction 7.9.7. 

The following example from the DY handler shows the handler responding 
to n special function call that requests the size of the currently mounted 
vohime. In this case, the larg:er of two possible diskettes is mounted. The 
handler uses $PUTWRD to move the size of the volume to the user buffer 
area. 



MOV #DDNBLK, -(SP) 
MOV DYGQE,R4 
JSR PC,@$PTWRD 



PUSH SIZE IN BLOCKS ONTO STACK 
POINT R4 TO Q.BLKN 
CALL THE ROUTINE 



7.9.7 Handlers That Access the User Buffer Directly 

Some situations call for combinations of the procedures described in the 
previous sections. Others require more effort on the handler's part to ac- 
com^plish a transfer. Some handlers cannot make good use of monitor 
routines and must access the user buffer directly. 

The DM handler for the RK06 disk, for example, normally uses the 
$MPPHY monitor routine to convert mapped addresses to physical ad- 
dresses. However, when a Cyclical Redundancy Check (CRC) error occurs, 
the handler performs its own mapping to the user buffer and then applies 
the correction for the error before continuing the transfer. The procedure 
for a handler to map to the user buffer is as follows. 

Devices such as the RXOl diskette transfer data one sector at a time be- 
tween the disk itself and an internal disk data buffer called a silo. However, 
the disk is not DMA, so the DX handler cannot use the $MPPHY monitor 
routine. Moreover, other monitor routines for character-oriented devices 
available to a silo device are too slow for practical use. So, the handler for 
the RXOl diskette maps to the user buffer in physical memory and then per- 
forms the I/O operation as though it were a simple transfer between 
memory and the. device. The handler implements this mapping by borrow- 
ing kernel PARI. (This is on(5 reason why the handler itself must not be 
located in the area mapped by PARI.) 

The first action the handler takes is to save the contents of PARI. Next it 
loads the Q.PAR value from the queue element into PARI, thus changing 
the kernel mapping. The hantiler can then access the user buffer area in 
physical memory by using the; 16-bit virtual buffer address in Q.BUFF — 
an address that is always within the PARI range of 20000 through 37776. 
Once the I/O transfer is compkjted, the handler restores the original value of 
PARI. 
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The following skeleton example shows how a handler can implement its own 
mapping. Assume that R4 points to the current queue element at its third 
word. 



KPAR1 = 172342 

MOV @#KPAR1,-(SP) 

MOV Q$PAR{R4),@#KPAR1 



MOV (SP) + ,@#KPAR1 



PARI REGISTER LOCATION 

SAVE OLD PARI ON STACK 

PUT NEW VALUE IN PARI 

ROUTINE TO EMPTY SILO, 

TRANSFER CONTENTS TO USER BUFFER, 

USING VALUE IN Q.BUFF. 

RESTORE PARI 



The following example is extracted from the DX handler and it illustrates 
how a handler performs its own mapping to the user buffer when it empties 
an internal silo. Assume at the start that R3 equals 128 decimal; R4 points 
to the CSR for the diskette; Rl contains the byte count for this transfer; 
and BUFRAD contains the user buffer addr,ess from Q.BUFF in the queue 
element. 





MOV 


@#KISAR1,-(SP) 


SAVE OLD PARI 




MOV 


DXCQE,R2 


POINT TO Q ELEMENT AT Q.BLKN 




MOV 


Q$PAR(R2),@#KISAR1 


MAP THE BUFFER VIA PARI 




ADD 


#2,Q$PAR(R2) 


CHANGE MAPPING TO BUMP ADDRESS 
FOR NEXT TIME 




CMP 


R1,R3 


MAKE SURE COUNT IS 128 OR LESS 




BLOS 


1$ 


OK IF SO 




MOV 


R3,R1 


RESET COUNT TO 128 


1$: 


MOV 


BUFRAD,R2 


GET USER VIRTUAL BUFFER ADDRESS IN R2 


2$: 


TSTB 


@R4 


WAIT FOR TRANSFER READY 




BPL 


2$ 


BRANCH IF TR NOT UP 


3$: 


MOVB 


@R5,(R2) + 


READ 




DEC 


R1 


CHECK FOR COUNT DONE 




BGT 


2$ 


STILL MORE TO TRANSFER 




MOV 


(SP) + ,@#KISAR1 


RESTORE PARI 



If your handler must access the user buffer directly, it is important for you 
to understand how PARI maps to the user area. Figure 7-5 is designed to 
clarify this point. It shows a virtual job in a typical XM system with the 
user buffer located in physical memory above the 28K word boundary. The 
user program is mapped to the buffer through PAR6. The handler borrows 
kernel PARI, puts the Q.PAR value from the queue element there, and then 
uses the Q.BUFF value from the queue element to access the user buffer. 

PARI maps to physical memory in units of 32-word decimal blocks and at 
most can map an area 4K words long. (Note that the page length of PDRl is 
always set to map the entire page.) If the user buffer starts at a location in 
physical memory that is not an even multiple of 32 words, PARI maps to 
the first 32-word boundary below the start of the buffer. The PARI map- 
ping area can start at any address in physical memory whose low-order two 
octal digits are 0. Thus, with a particular PARI mapping, as much as 4K 
words or 4K minus 31 decimal words, of the user buffer will be mapped. 
Figure 7-6 shows how this mapping works. 

Figure 7-6 shows a buffer area located at 331724 in physical memory with 
the application program mapped to the buffer through PAR6. The buffer is 
24 octal bytes above 331700, which is a 32-word boundary. The handler 
puts the Q.PAR value, 3317, into PARI, replacing the default PARI value 
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Figuire 7-5: Device Handler Iklapping to User Buffer Area 
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Figure 7-6: PARI Mapping 
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of 0200. This causes PARI to map to a 4K-word area in physical memory 
starting at address 331700. As a result, when the handler refers to kernel 
virtual addresses in the range 20000 through 37776, it accesses physical 
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memory locations 331700 through 351676. Since the value in Q.BUFF is 
20024, by using that value, the handler can access the start of the user buf- 
fer area at location 331724. 

If the amount of data to be transferred is large, you may need to advance 
the buffer pointer and adjust the mapping to account for it. There are two 
ways to advance the buffer pointer. The easier way is to modify PARI as 
you go. For example, for every 32 words you advance through the buffer, 
add 1 to the PARI value. The DX handler example just described transfers 
64 words at a time, adding 2 to PARI after each transfer to avoid mapping 
overflow. 

Another way to advance the buffer pointer is to modify the value of 
Q.BUFF by modifying the value in the queue element itself. In order to ad- 
just the mapping, step through the following procedures, thinking in terms 
of 4K-word units. First, after you modify the value of Q.BUFF, compare the 
new value to 40000. If the value is greater than or equal to 40000, subtract 
20000 from it, and add 200 to Q.PAR. These procedures take care of not on- 
ly adjusting the mapping, but also avoid mapping overflow. 

Finally, here are steps to follow to access any location in the user buffer 
area, if you are given a byte offset from- the beginning of the buffer. Essen- 
tially, you must determine the number of 32-word units in the offset by 
dividing the 16-bit byte offset by 100 octal and adding the quotient to 
PARI and the remainder to Q.BUFF. Then you will be able to access the 
correct location in the buffer. 

For example, suppose you needed to access the byte at offset 12345 from 
the start of the buffer shown in Figure 7-6. Dividing 12345 by 100 yields a 
quotient of 123 and a remainder of 45. Adding 123 to the current value of 
Q.PAR, which is 3317, yields 3442 for the new PARI value. Adding 45 to 
the value of Q.BUFF, which is 020024, gives 020071 as the new buffer ad- 
dress. (Note that this is a byte address.) 

7.10 System Device Handlers and Bootstraps 

In these sections, a description of monitor files precedes an explanation of 
how to create a system device handler or modify an existing handler to use 
as a system device. Within the main body of this explanation, details are 
given on the primary driver and on various bootstrap routines. The final 
sections provide background information on the DUP procedures for 
bootstrapping a new system device. 

7.10.1 Monitor Flies 

A monitor file must reside on your system device and can have any name 
you choose, but its required file type is .SYS. RT-11 distributed monitors 
are named RTllBL.SYS, RTllSJ.SYS, and RTllFB.SYS. If you create a 
monitor through the system generation process, its name is RTll:!c;c.SYG, 
where xx represents BL, SJ, FB, or XM. You must rename the monitor 
before you use it. 
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Blocks through 4 of each monitor file contain the secondary bootstrap. 
The secondary bootstrap loads the system device handler and the monitor 
into memory. It also modifies the monitor tables to connect the monitor 
with the device handler and assigns the default DK and SY names. 

The monitor file itself does not contain any device-specific code, nor does it 
have links to any specific device handler before bootstrap time. Instead, 
each device handler that can be used as a system device handler has a 
special block of device-speciiic code in it called the primary driver that is 
us<3d by the secondary bootstrap to read the system device handler file and 
the monitor file from the system device. The secondary bootstrap has room 
in its own block to store the primary driver. 

7.10.2 Creating a System Device Handler 

To create a system device handler, you must add the primary driver to a 
standard handler for a data device. 

A system device handler can contain SET options. So, if SET options are 
pairt of your handler, you need not remove them to create a system device 
handler. 

7.10.2.1 Primary Driver — Thes primary driver you add to a standard handler 
for a data device consists of four parts: 

• Entry routine 

• Software bootstrap 

• Bootstrap read routine 

• Bootstrap error routine 

The primary driver works together with the RT-11 bootstrap, B STRAP, to 
boot the new system device. The primary driver is contained entirely within 
the p-sect ddBOOT, where dd is the two-character device name. The code 
executes at location in physical memory. 

7.10.2.2 Entry Routine — The entry point for the primary driver is 
ddBOOT::. This location must contain only two instructions, and these 
must follow the DIGITAL standard bootstrap sequence. These instruc- 
tions are a NOP and a branch to the start of the software bootstrap. If the 
steirt of the software bootstrap is too far away for a branch, you can branch 
to a JMP instruction that starts the software bootstrap. The entry routine 
foi' the RK handler is as follows (BOOTl is defined in the primary driver): 

RKBOOT:: NOP 

BR B00T1 

Any hardware bootstrap causes the code in p-sect ddBOOT to load into 
memory at location 0. It also starts execution at ddBOOT::. 
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7.10.2.3 Software Bootstrap — The software bootstrap executes as the result 
of a jump or branch from the entry routine. Upon entry, all registers are 
available for use in the software bootstrap. The software bootstrap must 
perform the following functions in the order shown: 

1. Set up the stack at location 10000. 

2. Save the number of the device unit from which the system was just 
bootstrapped. (This is a value in the range through 7.) The method 
you use to find the unit number varies depending on the device; some 
unit numbers are passed in RO, and others must be extracted from the 
CSR. Save the unit number on the stack, and elsewhere in memory, if 
necessary. 

3. Call the bootstrap read routine to read in the rest of the bootstrap. 

4. Put a pointer in B$READ to the bootstrap read routine. 

5. Put the Radix-50 value for "B$DNAM" in B$DEVN. 

6. Store the device unit number in B$DEVU. 

7. Jump to B$BOOT in RT-ll's bootstrap to continue. 

The software bootstrap should be located in the primary driver immediately 
below location drfBOOT + 664. (Locations 664 through 776 contain the error 
routine created by .DREND.) 

7.10.2.4 Bootstrap Read Routine — The purpose of the bootstrap read routine 
is to read the volume in the device unit from which the system was just 
bootstrapped. It is called by both the RT-11 bootstrap and by the software 
bootstrap described in the previous section. 

The interface through which the other routines pass information to the 
bootstrap read routine is as follows: 

RO contains the block number to read. 

Rl contains the word count to read. 

R2 contains the memory buffer address into which to store the data. 

All registers are available for use in the bootstrap read routine, as is the 
stack. 

The bootstrap read routine must be a non-interrupt routine to read the 
volume according to the parameters passed in RO through R2. On error, the 
routine should jump to BIOERR. If there are no errors, it should return 
with an RTS PC instruction, with the carry bit clear. 

The bootstrap read routine should be located in your primary driver at loca- 
tion ddBOOT + 210. (Location 210 is the lowest address at which the read 
routine can be located.) 

7.10.2.5 Bootstrap Error Routine — The bootstrap error routine starts at loca- 
tion BIOERR::. The code in this routine is supplied completely by the 
.DREND macro, which you place at the end of the primary driver. 
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7.10.2.6 .DRBOT Macro — Use the .DRBOT macro to help you set up the 
primary driver. It also invokes the .DREND macro to mark the end of the 
handler so that the primary driver will not be loaded into memory during 
normal operations. In general, the code in the primary driver does not have 
to be Position-Independent. Klowever, any non-PIC reference must be ex- 
pressed relative to ddBOOT::. Note also that locations 60 through 206 are 
not iavailable for your use. 

The format for the .DRBOT macro is as follows: 

.DRBOT name,entry,reacl 

name is the two-character device name. 

entry is the entry point of the software bootstrap routine. 

read is the entry point of the bootstrap read routine. 

The .DRBOT macro puts a pointer to the start of the primary driver into 
location 62 of the handler file. It puts the length, in bytes, of the primary 
driver into location 64. The primary driver, including the error routine sup- 
plied by .DREND, must not exceed 1000 octal bytes. Location 66 contains 
the offset from the start of the primary driver to the start of the bootstrap 
read routine. 

Issue the .DRBOT macro call before the .DREND macro call. Then put the 
primary driver code between .13RB0T and .DREND, remembering that the 
primary driver must be one block or less in size — that is, it must be 1000 
octal bytes long or less, including the error routine and the locations from 
60 through 206. You may ha\^e noticed that the .DREND macro is called 
twice in a system device handler: once by .DRBOT, and once when you use 
it at the very end of the primary driver. The first occurrence of .DREND 
closes out the non-system seclion of the device handler and sets up a table 
of pointers into the monitor, ainong other things. The second .DREND call, 
the one you issue yourself, creates the B I OERR bootstrap error routine, in- 
stead of repeating the pointer table. 

If you use the BOOT command to bootstrap the new device, DUP passes 
the system unit number to the primary driver in location 4722 and in RO. If 
you bootstrap the device with a hardware bootstrap or some non-RT-11 
utility program, the primary driver must determine the device unit number 
that was booted and save it in location 4722 and in RO. 

For examples of the primary driver, see the handler listings in Appendix A. 

7.10.3 DUP and the Bootstrap Process 

This section shows how DUP carries out three commands related to 
bootstrapping. The commandsi are as follows: 

BOOT ddn:f Unarm 
COPY/BOOT xxn:filnam ddm: 
BOOT ddn: 

7.1 0.3.1 BOOT ddnif ilnam — Use the BOOT ddmfilnam command to perform 
a software bootstrap of a specific monitor file on a specific device. In the 
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command line, dd represents the two-character device name; n is its unit 
number. Both the new monitor file and the new device handler must be pre- 
sent on device dd. 

As soon as this command is issued, DUP first checks that device dd is a 
random-access device. Next, it locates the monitor file filnam.SYS on the 
device. (Note that the .SYS file type is both the default and the required file 
type.) It reads the first five blocks, blocks through 4, into a memory buf- 
fer. These blocks contain the secondary bootstrap for the monitor. 

The next-to-last word in block 4 contains the suffix for the handlers 
associated with this monitor. DUP uses this to build the file name of the 
device handler, usually dd.SYS or ddX.SYS. DUP reads block of the 
device handler fUe into a memory buffer, using the contents of locations 62 
and 64 to locate the primary driver, and reads it into a memory buffer. 

Next, DUP copies the primary driver into a buffer at the beginning of the 
secondary bootstrap, which is also in a memory buffer. It loads the informa- 
tion shown in Table 7-6 for the primary driver and the secondary bootstrap. 

Table 7-6: DUP Information 

Offset from Start 

of Memory Buffer Contents 

4722 Booted unit number 

4724-4726 Booted file name in Radix-50 

5000 Date at which booted 

5002-5004 Time at which booted 



DUP then copies the primary driver and secondary bootstrap from the 
memory buffer into memory locations through 5004. Then it jumps to 
location 1000 to start the secondary bootstrap at its DUP entry point so 
that the secondary bootstrap can load the monitor and the system device 
handler into memory. 

Figure 7-7 illustrates the entire procedure. 

7.10.3.2 COPY/BOOT xxn:filnam ddm: — Use the COPY/BOOT xxrufilnam 
ddm: to copy the secondary bootstrap from the monitor file on device xx to 
blocks 2, 3, 4, and 5 of device dd. In the command Une, xx represents the 
device on which the monitor file is stored; n is its unit number; dd 
represents the two-character name of the device that is to receive the 
bootstrap; m is its unit number. 

As soon as this command is issued, DUP checks that devices xx and dd are 
random-access devices. Next, it locates the monitor file filnam.SYS on the 
xxn: device. It reads the first five blocks of the monitor file, blocks 
through 4, into a memory buffer. These blocks contain the secondary 
bootstrap for the monitor. 

DUP locates the appropriate handler file on device dd. DUP then reads 
block of the device handler file into a memory buffer, using the contents of 
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Figure 7-7: BOOT ddnrfilnani Procedure 
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locations 62 and 64 to locate the primary driver, and reads it into a memory 
buffer. 

The handler for the system device dd must already be located on dd before 
you can copy the bootstrap to the device. DUP loads two words of 
Radix-50 for filnam into locations 4724 and 4726 of the memory buffer. 
Next, DUP copies the primary driver into block of device dd. Finally, 
DUI* writes the secondary bootstrap to blocks 2 through 5 of device dd. 

Figure 7-8 illustrates the entire procedure. 



7.10.3.3 BOOT ddn: — Use the BOOT ddn: command to perform a software 
bootstrap of a specific device that already has a specific monitor secondary 
bootstrap in blocks 2, 3, A, and 5 (placed there by the COPY/BOOT com- 
mand). In the command line, dd represents the two-character name of the 
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Figure 7-8: COPY/BOOT xxn:filnam ddm: Procedure 
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device to be booted; n is its unit number. Both the new monitor file and the 
new device handler must be present on device dd. 

As soon as this command is issued, DUE first checks that device dd is a 
random-access device. Then it reads blocks 2, 3, 4, and 5 into a memory buf- 
fer. These blocks contain the secondary bootstrap for the monitor. The 
primary driver is already in locations through 776. 

DUP locates the appropriate handler file on device dd. This procedure is a 
check that the volume has a system device handler stored on it so that it 
can be validly bootstrapped. 

DUP then extracts the file name of the monitor file from locations 724 and 
726 of block 4 and locates the monitor file on the device to make sure that it 
really exists. 

Next, DUP loads the information shown in Table 7-7 for the primary driver 
and the secondary bootstrap. 

Table 7-7: DUP Information 



Offset from Start 
of Memory Buffer 



Contents 



4722 
5000 
5002-5004 



Booted unit number 
Date booted 
Time booted 
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Dup then copies the primary driver and secondary bootstrap from the 
device into memory locations through 4777. Then it jumps to location 
1000 to start the secondary bootstrap at its DUP entry point so that the 
secondary bootstrap can load the monitor and the system device handler in- 
to memory. 

Figuire 7-9 illustrates the entire procedure. 
Figmre 7-9: BOOT ddn: Procedure 
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7.11 How to Assemble, Link, and Install a Device Handler 

Assembling, linking, and installing a new device handler are very simple 
procedures described in detail in the following sections. 

7.11.1 Assembling a DevidB Handler 

Your MACRO-11 source file should be named dd.MAC, where dd is the two- 
character device name. For clarity, use the /SHOW:MEB assembler option 
to print the expansions of macros such as .DRBEG and .DRAST. 
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To assemble a handler for an SJ or FB system, use the following command: 

MACRO/CROSSREFERENCE/SHOW:MEB/LIST SYCND + dd/OBJ ECT 

To assemble a handler for an XM system, use the following command: 

MACRO/CROSSREFERENCE/SHOW:MEB/LIST XM + SYCND + dd/OBJ ECT:ddX 

XM is a source file distributed with RT-11 that indicates that the extended 
memory feature is present, as is support for the foreground/background 
environment. 

SYCND is the system conditional file. If your system was produced 
through the system generation process, you must use this file when you 
assemble your handler so that the handler conditionals will match the 
monitor conditionals and the handler will operate in the correct environ- 
ment. Omit this file if you are assembling a device handler that will run with 
a distributed RT-11 monitor, or use the SYCND.DIS file that is part of the 
distribution kit. 

7.11.2 Unking a Device IHandler 

Once your source file assembles without errors, you are ready to link it. To 
link a handler for an SJ or FB system, use the following command: 

LINK/MAP/EXECUTE:dd.SYS dd 

To link a handler for an XM system, use the following command: 
LINK/MAP/EXECUTE:ddX.SYS ddX 



7.11.3 Instaiiing a Device Handler 

Before you can use your new handler, you must add information about it to 
the monitor device tables described in Chapter 3 of this manual. The proc- 
ess of adding a new device is called installation. There are two separate 
routines in the RT-11 system that can install a device handler: the 
bootstrap and the monitor INSTALL command. Both routines require a 
device's hardware to be present on the system before they install the device 
handler. (Section 7.11.3.6 describes a way to circumvent this restriction if 
you need to install a handler for a nonexistent device.) 

The following sections describe the various ways to install device handlers 
in an RT-11 system. 

7.11.3.1 Using the Bootstrap to Install Handlers Automatically — The bootstrap 
routine first locates the system device handler on the device from which you 
booted the system, and installs it. Then it scans the rest of the handler files 
on the system device and tries to install the corresponding handler for each 
hardware device it finds on the system. If the hardware is not present, the 
bootstrap does not install the device. 

The only difficulty with this procedure occurs when there are more handler 
files than device slots. A distributed monitor reserves one device slot for 
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each device RT-11 supports. A monitor you create through system genera- 
tion reserves one slot for each device you request. In addition, it provides 
the number of empty slots you specify. A slot is considered to be reserved 
for a particular device if the $PNAME monitor table has an entry for that 
device. A slot is empty if $PN AME has a zero word. 

The automatic device installation routine in the bootstrap has a set of 
priorities to determine which handlers to install when there are more 
handlers than slots. If all slots are empty, the bootstrap installs the system 
device handler plus the first handlers it encounters on the system device 
whose device handware is present. For example, if a system has eight slots, 
all empty, the bootstrap installs the system device handler and the first 
seven legitimate handlers it finds on the system device. 

If one or more slots are reserved for specific devices (that is, the devices 
hav(} entries in the $PNAME table), the bootstrap reserves those slots for 
the corresponding handlers imtil it can verify the presence of the ap- 
propriate hardware. If the hardware exists, the bootstrap installs its device 
handler. If the hardware is not present, the bootstrap clears its $PNAME 
entry, thus creating an empty slot. 

Figvire 7-10 summarizes the algorithm the bootstrap uses to install device 
handlers. 

As you can see, handlers with entries in the $PNAME table have higher 
priority at boot time. If the handler file is on the system device and the 
device hardware exists, the bootstrap always installs the handler. 

When you write a device handiler yourself, you should have no problem in- 
stalling it in your RT-11 system because you can rely on the bootstrap to 
install the handler for you if the handler resides on the system device, if its 
hardware is present, and if there is an empty slot in the monitor tables. If 
your system has no free slot, you can create one or more by simply storing 
fewesr device handler files on your system device and rebooting the system. 
You can also use the monitor INSTALL command (described in Section 
7.11.3.2) to install a new handler without rebooting the system. (This new 
handler may be one that the biootstrap could not install due to lack of free 
slots, or it may be a new handler that you just created or just copied to the 
system device.) Or, if you created your system through system generation, 
you can use the DEV macro (described in Section 7.11.3.3) to reserve a slot 
for a new device handler and give it priority for installation at bootstrap 
timei. Figure 7-11 summarizes the ways you can install a new device 
handler, 

7.11.3.2 Using the INSTALL Command to Install Handlers Manually — Before us- 
ing the INSTALL command to install a handler manually, use the SHOW 
command to see if there are any empty device slots on your system. If there 
are none, use the REMOVE command to remove a device you do not need 
and make room for your new device, which you add by using the INSTALL 
command. The formats of thesie commands are documented in Chapter 4 of 
the .RT-11 System User's Guide. 

If a device slot was already available, your device will install automatically 
the next time you bootstrap the system. If you used REMOVE and IN- 
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Figure 7-10: Bootstrap Algorithm for Installing Device Handlers 
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STALL to add your new device to the system, you must reissue the com- 
mands after each bootstrap. To install the new device automatically at each 
bootstrap, put REMOVE and INSTALL commands in your system's start- 
up indirect file. This saves you the trouble of typing the commands 
yourself. In addition, it gives the device the appearance of being permanent- 
ly installed. 

7.11.3.3 Using the DEV Macro to Aid Automatic Installation — If you created 
your system through a system generation, you can edit a system 
MACRO-1 1 source file to add a new device to the $PNAME table, thus giv- 
ing it preference in the automatic handler installation procedure. The file 
you edit is SYSTBL.MAC, one of the files you assemble to create a mon- 
itor file. 

Use the DEV macro in the file SYSTBL.MAC to add a new device to the 
system permanently. The format of the DEV macro is as follows: 

DEV name.s 
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Figuire 7-11: Installing a New Device Handler 
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name is the two-character device name. 

s represents the device status word (leave this argument blank). 

The following examples are taken from the SYSTBL file: 



DEV RK 
DEV LP 
DEV MT 



INSTALLS THE RK DISK 
INSTALLS THE LINE PRINTER 
INSTALLS MAGTAPE 



After you edit SYSTBL.MAC to add the DEV macro call for your device, 
you must reassemble it. Use the following command: 



MACRO/OBJ ECT:TBxx xx + SYCND + SYSTBL 



XX represents SJ, FB, or XM. SJ.MAC, FB.MAC, and XM.MAC are files 
distributed with RT-11; they indicate whether or not fore- 
ground/background processing is permitted. XM.MAC also indicates that 
extended memory support is piresent. Once the assembly is complete, relink 
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the object files to create your new monitor. Follow the commands in the 
command file that resulted from your system generation procedure. 

7.11.3.4 Installing Devices Whose Hardware Is Present — Both routines in 
RT-11 that can install a device handler — the bootstrap code and the 
monitor INSTALL command code — install handlers only for those devices 
whose hardware is present on the current system configuration. The 
routines look at location 176 in block of the handler and test the address 
that 176 contains, which is normally the CSR for the device. If the hardware 
for the device is not present on the system, a bus time-out occurs, causing a 
trap to 4, which the installation routines field. As a result, neither the 
bootstrap routine nor the INSTALL command will install the device 
handler. In addition, the INSTALL command prints the ?KMON-F-Illegal 
device installation message. 

The installation routines think the device's hardware is present if its CSR 
responds on the bus. However, this simple test is not sufficient to deter- 
mine, in some cases, which hardware device is present. For example, some 
devices are assigned the same addresses in the I/O page for one or more of 
their status registers. If RT-11 just tested a "shared" I/O page address, it 
still doesn't know which of two devices is really present and therefore which 
handler to install. The RXOl and RX02 diskette devices, for example, have 
the same bus address and the same number of status registers in the I/O 
page. When RT-11 attempts to install the DX handler, it must be able to 
determine whether or not hardware is present, and whether or not it is the 
RXOl device. Clearly, it should not install the DX handler when the hard- 
ware is really the RX02 device. 

There is always some difference between two or more devices that is 
discernible from their registers in the I/O page. Each handler for one of the 
hard-to-identify devices can test for this difference and inform the RT-11 
installation routine whether or not it should install the device handler it is 
currently considering. 

7.11.3.5 Writing an Installation Verification Routine— RT-11 handlers for 
devices with shared I/O page addresses aU contain an installation verifica- 
tion routine to distinguish which hardware device is actually present and to 
permit or inhibit installation of the current handler. If you write a device 
handler yourself, you can include your own installation verification routine. 

In general, the installation verification routines distinguish which hardware 
is present based on one of the three following conditions: 

• Of the two devices that share some registers, one device has more 
registers than the other. 

• If two devices share addresses for all their registers, and if they have 
the same number of registers, sometimes one device has a read/write 
bit where the other device has a read-only bit. 

• Sometimes a device has a unique identification bit or byte. 
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The installation verification routines, then, determine which device is pre- 
sent based on the results of tessting one of the distinguishing conditions. 
Once this determination has been made, the routine signals to the RT-11 in- 
stallation routine whether or not to install the current handler and then 
returns to the monitor with the carry bit set to prevent installation and 
with the carry bit clear to pernoit installation. 

Note that your installation verification routine has all the general registers 
available for your use. 

Entry Points of the Installation Verification Routine 

An installation verification routine that you write in your own handler 
starts at location 200 in block of the handler. It must not extend beyond 
location 356. Location 200 is the entry point that the bootstrap code uses to 
install a data device. The INSTALL monitor code always enters here, as 
well. 

Location 202 is the entry point that the bootstrap code uses to install the 
system device. The INSTALL monitor code never enters here. 

If you do not care whether youi- handler is installed as the system device or 
as a data device, put a NOP instruction at location 200. If your handler 
must be installed as the system device handler, use the following instruc- 
tions to prevent its installation under any other circumstances: 

.= 200 ;NON-SYSTEM ENTRY POINT 

BR ERROR :BRANCH TO ERROR ROUTINE 



ERROR: SEC ;SET CARRY TO PREVENT INSTALLATION 

RTS PC ;AND RETURN 

// the Hardware for This Handler Has an Extra Register 

If this handler is for a device that shares an I/O page address with another 
device, you can identify which device is present if the two devices have a dif- 
ferent number of registers. When the device for the current handler has one 
more register than the other device, use the following instioictions to test 
for the extra register: 

MOV 176,R0 ;GET THE SHARED CSR 

TST n(RO) ;TEST THE EXTRA REGISTER AT OFFSET n 

;FROM THE SHARED GSR 
RTS PC iRETURN (WITH CARRY SET IF WRONG DEVICE) 

This routine tests the extra register. If there is no device configured there, 
the bus times out, causes a trap to 4, and sets the carry bit. The installation 
verification routine returns to t;he monitor with the carry bit set, indicating 
that the correct hardware for the current handler is not present, and that 
this handler should not be installed. 

On the other hand, if the extra register reponds to the test, the TST instruc- 
tion returns with the carry bit clear, which means that the correct hardware 
for this device handler is present, and that RT-11 should install the handler. 
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If the Hardware for This Handler Has Fewer Registers 

If the hardware for the other device that shares an I/O address with the 
device for this handler has more registers, this handler can test for the 
absence of the extra register. If the extra register is not found, RT-11 
should install the current handler. 

The following instructions take care of this situation: 

GET THE SHARED GSR 

TEST THE EXTRA REGISTER AT OFFSET n 

FROM 176. IS A DEVICE HERE? 

YES, OTHER DEVICE IS HERE. 

NO, CLEAR CARRY 

INSTALL CURRENT HANDLER 



1$: 



MOV 
TST 


176,R0 
n(RO) 


BCC 
CLC 
RTS 


1$ 
PC 


SEC 

RTS 


PC 



SET CARRY 

DO NOT INSTALL CURRENT HANDLER 



Essentially, this routine checks for the presence of the other device's extra 
register. If it is not present, the routine instructs RT-11 to install the cur- 
rent handler. 

// an Identification Bit or Byte Exists 

If the devices that share an I/O page address also share an identification bit 
or byte, an installation verification routine can check the bit or byte and 
determine which hardware is present. It can then permit or inhibit the in- 
stallation of the current handler based on that information. 

In RT-11, for example, the RXOl and RX02 devices share the CSR. Bit 11, 
called CSRX02, is clear if the device is an RXOl, and set if the device is an 
RX02. The following example is from the DY device handler, which should 
only be installed if RX02 hardware is present. 

VERIFICATION ROUTINE GOES HERE 
SAME CHECK FOR SYSTEM AND NON-SYSTEM 
IS RX02 BIT ON? 

NO, THIS IS AN RXOL DON'T INSTALL THIS 
DY HANDLER. 

CLEAR CARRY, SKIP SEC INSTRUCTION. 
WE HAVE AN RX02, SO INSTALL DY HANDLER 
1$: SEC ;SET CARRY, DON'T INSTALL DY HANDLER 

RETURN TO MONITOR 

If One Device Has a Read/Write Bit 

If one of the devices that share an I/O page address has a read/write bit in 
the CSR where the other device has a read-only bit, the verification routine 
can determine which hardware is present by following a general procedure 
to check the bit and permit or inhibit the installation of the current handler 
based on the results. The routine should read the bit, toggle it, and write it 
back to the CSR. Then the routine should read the bit again. If the value of 
the bit changed, the device with the read/write register is present. If the 
value remained constant, the device with the read-only register is present. 
The routine can set the carry bit appropriately and return to the monitor. If 



.ASECT 
. = 200 
NOP 
BIT 
BEQ 


#CSRX02,@176 
1$ 


TST 


(PC) + 


SEC 
RTS 


PC 



7-64 Device Handlers 



carry is set, RT-11 does not install this handler. If carry is clear, RT-11 
does install this handler, 

7.11.3.6 Overriding the Hardware) Restriction — If for any reason you need to 
install a device handler whose hardware is not present in your current 
syst€sm configuration, you can circumvent the bootstrap and INSTALL 
routines by running SIPP. You clear locations 176 and 200 in the handler 
file's block 0, then use the INSTALL command or reboot the system to in- 
stall the device handler. 

7.12 How to Test and Debug a Device Handler 

Once your new handler is assembled, linked, and installed, you are ready to 
begin testing it. Remember during debugging that you must remove the old 
handler and install the new c»ne each time you create a new version of 
dd(X).SYS. 

Test the handler in three stages, according to these guidelines: 

1. Use ODT to observe the liandler as it processes a data transfer. Sec- 
tions 7.12.1 and 7.12.2 describe how to do this. 

2. Test the handler with keyboard monitor commands, with system utili- 
ty programs, and with F(DRTRAN IV or BASIC-11. Try the COPY 
command, for example, to copy data to and from the device, or run PIP 
to do the same thing. Try using the handler with FORTRAN READ or 
WRITE statements, or with BASIC INPUT or PRINT statements. If 
your handler sets the bit in the device status word that indicates that 
the handler is for an RT-11 directory- structured device, DUP will 
operate correctly on the device with no further modifications. That is, 
you should be able to us<} DUP to initialize the device (through the 
INITIALIZE command) and to consolidate free space (through the 
SQUEEZE command). The RESORC program needs no modification 
to recognize the new device and will include it in its SHOW DEVICES 
report. 

3. Give the handler an exteiided workout with an application program 
that uses wait-mode I/O, asynchronous I/O, and completion routines. 

When the handler passes all the tests successfully, you can begin using it as 
part of your regular RT-11 system. If you are lucky, it wiU work perfectly 
the first time! 

NOTE 

Handlers for magtape devices are slightly more difficult to 
interface to the system, since MDUP (which you need to 
build a bootable magtape) does not immediately recognize 
devices other than those supported by RT-11. See the 
RT-11 Installation and System Generation Guide for in- 
structions on rebuilding MDUP; see the RT-11 System 
Release Notes for patches to DUP and MDUP. (Other 
utilities can use the new magtape handler.) 
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You also need to patch DUP if your new device accepts 
variable size volumes, or if it supports bad block replace- 
ment. See the RT-11 System Release Notes for these 
patches. 

7.12.1 Using ODT to Test a Handler 

The easiest way to use ODT to test a handler is to run ODT as the 
foreground job. If you normally use only the SJ monitor, it is worthwhile to 
switch to FB just for debugging. 

Since you will be doing some careful debugging work, DIGITAL also 
recommends that you be the sole user during this time. Bring up your 
system from a hardware bootstrap. Do not start any system jobs or load 
any handlers. If you are using a VTll or VS60 display terminal, issue the 
GT ON command now. This puts the GT handler high in memory, just 
under the Resident Monitor. 

(The examples shown in this discussion were created by testing the DX 
handler on a PDP-11/05 with 28K words of memory and a VTll display 
terminal.) 

Link ODT for the foreground with the following command: 

LINK/MAP/FOREGROUND ODT 

Next, load the device handler you need to debug: 
LOAD ofof[X] 

Now, look at the Unk map for ODT. Determine the length of ODT by 
subtracting 1000 from its high limit. For this example, the high Umit is 
7100. The length of ODT is then 6100 octal words. 

Start ODT as the foreground job. Use the IP option to pause and print 
ODT's load address: 

FRUN ODT/P 
Loaded at 123532 

Then issue the RESUME command to start ODT: 

RESUME 
ODTV01.04 



Since ODT is the foreground job and the last handler loaded is the handler 
to be debugged, the handler is located just above ODT in memory. Put the 
load address of ODT into relocation register 0: 

123532;0R 

Open the location just after ODT in memory by using the size of ODT offset 
from relocation register 0: 

0,6100/ 704 
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The word at the location just after ODT in memory indicates the length of 
the device handler. The monitor puts this word in memory as part of its 
mechanism for handling free space. The length of the handler is actually 702 
octal words. The value 704 inclvides the size word, which is not really part of 
the handler. So, the location just after the size word is the start of the 
device handler. Reset relocation register to the start of the handler: 

0,6102;0R 

Figure 7-12 illustrates the arrangement of components in memory at this 
point. 

Figure 7-12: ODT and a Device Handler in Memory 
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You <;an step through the handler in memory as you follow the instructions 
in your assembly Usting. The iirst five words are the header; the first ex- 
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ecutable instruction is the sixth word. Set your first breakpoint at the sixth 
word: 

0,12;0B 

Set other breakpoints at various points in the handler that you want to ex- 
amine during debugging. Another critical place is the interrupt entry point. 
You can find its location by checking the handler's MACRO- 11 listing. 
Remember, the interrupt entry point is called ddINT:; you should be able to 
find it easily and set a breakpoint there. 

When you have finished setting breakpoints in the handler, exit from ODT: 

0;G 

Now try using the handler. You could try using DUP to initialize the device, 
or PIP to copy data to the device. Or, run a test program that you have 
designed especially for this purpose. When execution reaches the first 
breakpoint in the handler, ODT takes control. Use ODT as usual to examine 
locations and check their values, or to modify instructions. Note that the 
default priority of ODT is 7; this prevents other interrupts from disturbing 
your debugging session. Since you are the only user on the system, ODT's 
high priority should cause no problem. (Note, however, that the system 
clock wiU lose time, and that ODT usually cannot debug race conditions.) 

When you are satisfied with the handler's performance, remove the break- 
points from it and proceed with the remainder of execution through the 
handler: 

;B 
;P 

Be careful not to unload the foreground job (ODT) while there are still 
breakpoints set in the handler. 



7.12.2 Using ODT in XM 

By following just a few special guideUnes you can use ODT to debug an XM 
device handler. 

Carefully select a place for ODT in memory. You can Unk it with an apphca- 
tion program, or link it so it resides somewhere in memory where it will not 
be destroyed. If a breakpoint is to be taken in kernel mode, ODT must not 
reside in the PARI area (locations 20000 through 37776). The safest place 
to put ODT is in the foreground partition, as described in Section 7.12.1. 

When you are debugging with ODT, the I/O page must always be mapped. 

Setting breakpoints also requires care. As soon as you enter ODT, look at 
the breakpoint trap vector (BPT) at locations 14 and 16 in low memory. 
When you set a breakpoint you must manually set the current mode bits, 
bits 14 and 15, of the PS at location 16. Set them to the current mode you 
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expect at the time the breakpoint occurs. The values are 11 for user mode, 
and 00 for kernel. RT-11 utility programs such as PIP and DUP run in user 
mode and expect the mode bits to be set to 11. 

After setting breakpoints, type 0;G to exit from ODT. This causes ODT to 
perfojt-m an .EXIT request, which destroys the BPT vector. So, after you 
exit from ODT, you must manually reconstruct the contents of the vector 
by using the Deposit command, as follows: 

D 14 = (correct contents of 14),(correct contents of 16) 

Make sure no other jobs are running when you do this, since context switch- 
ing causes this technique to fail. 
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Chapter 8 
File Formate 



This chapter describes the formats of various RT-11 files. It contains infor- 
mation on the following file types: 

Object files (OBJ) 

Symbol table definition fiUiS (STB) 

Library files (OBJ and MAC) 

Absolute binary files (LDA) 

Save image files (SAV) 

Relocatable files (REL) 

Stream ASCII files (such sis MAC, FOR, and so on) 

CJREF files 

Error log files 



8.1 Object File Format (OBJ) 



An object module is a file containing a program or routine in a binary, 
relocatable form. Object files normally have an .OBJ file type. In a 
MACRO- 11 program, one module is defined as the unit of code enclosed by 
the .TITLE and .END pair of directives. MACRO-11 takes the module 
name from the .TITLE statement. Language processors, such as 
MACRO-11 and FORTRAN IV, produce object modules; the linker proc- 
esses object modules to make njmnable programs in SAV, LDA, or REL for- 
mat. The librarian can also process object files to produce library files, 
which the linker can then use. Figure 8-1 illustrates object module 
processing. 

Although you can combine many different object mbdules to form one file, 
each object module remains coruplete and independent. However, when the 
libraiian combines object modules into a library, the modules are no longer 
independent. Instead, they are concatenated and become part of the 
libraiy's structure. The librarian concatenates modules by byte rather than 
by word in order to save space. For example, suppose a library is to consist 
of two modules, and the first module contains an odd number of bytes. The 
librai-ian adds the second module to the library behind the first module and 
positions the first byte of the second module as the high-order byte of the 
last word of the first module. As a result of this procedure one byte is saved 
in the library. 
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Figure 8-1: Object Module Processing 
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To understand byte concatenation, it is most helpful to think of the 
modules as a stream of bytes, rather than as a stream of two-byte words. 
Figure 8-2 shows how two five-byte modules would be concatenated. 
Module 1 and module 2 are shown both as bytes and as words. 

The rest of Section 8.1 contains information on the composition of object 
modules that is more detailed than most programmers require. However, if 
you intend to write a language processor, a linker program, or a program to 
dump and interpret object modules, you should read this material carefully. 
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Figure 8-2: Modules Concatenated by Byte 

BYTES: 



MODULE 1: 
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MODULE 2: 



MODULE 1: 



MODULE 2: 



2 


1 


4 


3 




5 



CONCATENATED MODULES, MODULE 1 FOLLOWED BY MODULE 2: 



BYTES: 



MODULE 1: 



MODULE 2: 



WORDS: 



2 


1 


4 


3 


1 


5 


3 


2 


5 


4 



If you are writing a language processor and want its output to be processed 
by the RT-11 linker, be sure that the processor produces object modules 
compatible with those describejd here. Since this section documents the ob- 
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ject modules produced by MACRO-11 and FORTRAN IV, you could also 
use this information to write your own linker program. 

Object modules are made up of formatted binary blocks. A formatted 
binary block is a sequence of eight-bit bytes (stored in an RT-11 file, on 
paper tape, or by some other means) that is arranged as shown in 
Figure 8-3. 

Figure 8-3: Formatted Binary Format 
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Each formatted binary block has its length stored within it. The length in- 
cludes all bytes of the block except the checksum byte. The checksum byte 
is the negative of the sum of all preceding bytes. Formatted binary blocks 
may be separated by a variable number of null (0) bytes. 

The "data bytes" portion of each formatted binary block contains the ac- 
tual object module information. RT-11 uses and recognizes eight types of 
data blocks. The information in these blocks guides the linker as it 
translates object code into a runnable program. Table 8-1 lists the eight 
types of data blocks. 

Table 8-1: RT-11 Data Blocks 



Identification 
Code 


Block Type 


Function 


1 


GSD 


Holds the Global Symbol Directory informa- 
tion 


2 


ENDGSD 


Signals the end of Global Symbol Directory 
blocks in a module 


3 


TXT 


Holds the actual binary text of the program 


4 


RLD 


Holds Relocation Directory information 


5 


ISD 


Holds the Internal Symbol Directory informa- 



tion (not supported by RT-11) 



8-4 File Formats 



Table 8-1: RT-11 Data Blocks (Cont.) 



Identification 
Code 


Block Type 


Function 


6 


ENDMOD 


Signals the end of the object module 


7 


Librarian heeider 


Holds the status of the library file (see Section 
8.3.1) 


10 


Librarian end 


Signals the end of the library file (see Section 
8.3.3) 



An object module must begin with a Global Symbol Directory (GSD) block 
and end with an End of Module (ENDMOD) block. Additional GSD blocks 
can occur anywhere in the file, but must appear before an End of Global 
Symbol Directory (ENDGSD) block. An ENDGSD block must appear 
before the ENDMOD block, and at least one Relocation Directory (RLD) 
block must appear before the first Text Information (TXT) block. Addi- 
tioned RLD and TXT blocks can appear anywhere in the file. The Internal 
Symbol Directory (ISD) block can appear anywhere in the file between the 
initial GSD and ENDMOD blocks. Figure 8-4 shows a general scheme for 
an object module. 

You must declare all program sections (PSECTs, VSECTs, and CSECTs) 
defined in a module in GSD items. The size word of each program section 
definition should contain the size in bytes to be reserved for the section. If 
you declare a program section more than once in a single object module, the 
linker uses the largest declared size for that section. All global symbols that 
are defined in a given program section must appear in the GSD items im- 
mediately following the definition item of that program section. 

A special program section, called the absolute section (. ABS), is allocated 
by the linker beginning at location of memory. Immediately after the 
GSD item that defines the absolute section, declare all global symbols that 
contain absolute (non-relocatatile) values. If you do not want to allocate any 
memory space for the absolute section, specify zero as its size word. You 
can do this even if absolute global symbol definitions occur after it. 

Global symbols that are referenced but not defined in the current object 
module must also appear in GSD items. These global references may appear 
in any GSD item except the very first, which contains the module name. In 
MACRO, referenced globals are seen in a GSD block under the . ABS. 
p-sect. They always have the p-sect definition preceding them. 

Note that when a 16-bit word is stored as part of the information in a data 
block, it is always stored as tv/^o consecutive eight-bit bytes, with the low- 
ordeif byte first. 

Object module data blocks vary^ in length. The first byte in a data block is a 
code that identifies the type of data block. The codes range from through 
10 octal, as Table 8-1 shows. The format of the rest of the information in 
the data block depends on the type of data block. 
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Figure 8-4: General Object Module Format 
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The following sections describe in detail the format of the data blocks. 



8.1.1 Global Symbol Directory Block (GSD) 

Global Symbol Directory blocks contain all the information the linker needs 
to assign addresses to global symbols and to allocate the memory a job re- 
quires. Table 8-2 shows the eight types of entries that GSD blocks can 
contain. 



Table 8-2: Entries in GSD Blocks 

Entry Type Description 

Module Name 

1 Control Section Name (CSECT) 
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Table 8-2: Entries in GSD Blocks (Cont.) 
Eifttry Type Doscription 



2 Internal Symbol Name 

3 Transfer Address 

4 Global Symbol Name 

5 Program Section Name 

6 Program Version Identification (IDENT) 

7 Mapped Array Declaration (VSECT) 



Each entry type is represented by four words in the GSD data block. The 
first two words contain six Radix-50 characters. The third word contains a 
flag byte and the entry type identification. The fourth word contains addi- 
tional information about the entry. Figure 8-5 illustrates the format of the 
GSD data block and the entry types. 

Figure 8-5: Global Symbol Directory Data Block 
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The following sections describe the entry types for GSD data blocks. 
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8.1.1.1 Module Name (Entry Type 0) — The module name entry (see Fig- 
ure 8-6) declares the name of the object module. The name need not be 
unique with respect to other object modules because modules are identified 
by file, not module name. However, only one module name declaration can 
occur in a single object module. 

Figure 8-6: Module Name Entry Format (Entry Type 0) 





MODULE 
NAME 













1 



8.1.1.2 Control Section Name (Entry Type 1) — The control section name entry 
(see Figure 8-7) declares the name of a control section. The linker converts 
control sections — which include ASECTs, blank CSECTs, and named 
CSECTs — to p-sects. For compatibility with other systems, the linker 
processes ASECTs and both forms of CSECTs. See Section 8.1.1.6 for the 
entry the linker generates for a .PSECT statement. 

You can define ASECT and CSECT statements in terms of PSECT 
statements, as follows: 

For a blank CSECT, define a p-sect with the following attributes: 

.PSECT ,RW,l,LCL,REL,CON 

For a named CSECT, the p-sect definition is: 
.PSECT name,RW,l,GBL,REL,OVR 

For an ASECT, the p-sect definition is: 
.PSECT . ABS.,RW,l,GBL,ABS,OVR 

The linker processes ASECTs and CSECTs as PSECTs with the fixed at- 
tributes defined above. 

Figure 8-7: Control Section Name Entry Format (Entry Type 1) 
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8.1.1.3 Internal Symbol Name (E-ntry Type 2) — The internal symbol name en- 
try (see Figure 8-8) declares the name of an internal symbol with respect to 
the module. Because the linker does not support internal symbol tables, the 
detailed format of this entry is not defined. If the linker encounters an inter- 
nal symbol entry while readini? the GSD, it ignores it. 

Figuire 8-8: Internal Symbol Name Entry Format (Entry Type 2) 



— 


SYMBOL 
NAME 


— 


2 





UNDEFINED 



8.1.1.4 Transfer Address (Entry Type 3)— The transfer address entry (see 
Figure 8-9) declares the transfer address of a module relative to a p-sect. 
The first two words of the entry define the name of the p-sect. The fourth 
word indicates the relative offset from the beginning of that p-sect. If no 
transfer address is declared in a module, the transfer address entry must 
not be included in the GSD, or else a transfer address 000001 relative to the 
default absolute p-sect (. ABS.) must be specified. 

To begin execution of a program within a particular object module of a pro- 
gram, specify the starting address to the Unker as the transfer address. The 
linker passes the first even transfer address it encounters to RT-11 as the 
program's starting address. Whenever the resulting program executes, the 
start address indicates the first executable instruction. If there is no 
transfer address (if, for example, you did not specify one with the .END 
directive in a MACRO-11 program), or if all transfer addresses are odd, the 
resulting program does not self-start when you run it. 

Figure 8-9: Transfer Address Entry Format (Entry Type 3) 



SYMBOL 
NAME 



OFFSET 



NOTE 

When the p-sect is absolute. Offset is the actual transfer 
address if it is not equial to 000001. 
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8.1.1.5 Global Symbol Name (Entry Type 4) — The global symbol name entry 
(see Figure 8-10) declares either a global reference or a definition. All defini- 
tion entries must appear after the declaration of the p-sect under which 
they are defined, and before the declaration of another p-sect. Global 
references can appear anywhere within the GSD. 

Figure 8-10: Global Symbol Name Entry Format (Entry Type 4) 







SYMBOL 
NAME 


4 


FLAGS 






VALUE 



The first two words of the entry define the name of the global symbol. The 
flag byte declares the attributes of the symbol. The fourth word contains 
the value of the symbol relative to the p-sect under which it is defined. 

The flag byte of the symbol declaration entry has the bit assignments 
shown in Table 8-3. Bits through 2, 4, 6, and 7 are not used by the RT-11 
linker. 

Table 8-3: Flag Bits for Global Symbol Name Entry 
Bit Meaning 

3 Definition 

= Global symbol reference 

1 = Global symbol definition 

5 Relocation 

= Absolute symbol value 

1 = Relative symbol value 



8.1.1.6 Program Section Name (Entry Type 5) — The p-sect name entry (see 
Figure 8-11) declares the name of a p-sect and its maximum length in the 
module. It also uses the flag byte to declare the attributes of the p-sect. The 
default attributes of the p-sect (blank or named with no attributed 
specified) are as follows: 

.PSECT ,RW,l,LCL,REL,CON 

NOTE 

The length of all absolute sections is zero. 

GSD records must be constructed in such a way that once a p-sect name has 
been declared, all global symbol definitions pertaining to it must appear 



8-10 File Formats 



Figure 8-11: P-sect Name Entry Format (Entry Type 5) 



P-SECT 
NAME 



FLAGS 



MAXIMUM LENGTH 



before another p-sect name is declared. Global symbols are declared by 
means of symbol declaration entries. Thus, the normal format is a series of 
p-sect names, each followed by optional symbol declarations. 

Table 8-4 shows the bit assignments of the flag byte. Bits 0, 1, and 3 are not 
used by the RT-11 linker. 



Table 8-4: Flag Bits for P-sect Name Entry 
Meaning Bit 



Allocation 

= P-sect references are to be concatenated with other 

references to the same p-sect to form the total amount 
of memory allocated to the section. 

1 = P-sect references are to be overlaid. The total amount 

of memory allocated to the p-sect is the size of the 
largest request made by individual references to the 
same p-sect. 

Access (not supported b»y RT-11 monitors) 

= P-sect has read/write access. 

1 = P-sect has readonly access. 

Relocation 

= P-sect is absolute and requires no relocation. 

1 = P-sect is relocatable and references to the control sec- 

tion must haves a relocation bias added before they 
become absolute. 

Scope 

= The scope of the p-sect is local. References to the same 

p-sect will be collected only within the overlay segment 
in which the p-siect is defined. 

1 = The scope of the p-sect is global. References to the 

p-sect are collected across overlay segment boundeuues. 

Type 

= The p-sect contains instruction (I) references. Con- 

catenation of this p-sect will be by word boundary. 
Globals will be given overlay control blocks. 

1 = The p-sect contains data (D) references. Concatenation 

of this p-sect wiU be by byte boundary. Globals will not 
go through the overlay handler. 
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8.1.1.7 Program Version Identification (Entry Type 6) — The program version 
identification entry (see Figure 8-12) declares the version of the module. 
The linker saves the version identification, or IDENT, of the first module 
that defines a nonblank version. It then includes this identification on the 
memory allocation map. 

The first two words of the entry contain the version identification. The 
linker does not use either the flag byte or the fourth word because they con- 
tain no meaningful information. 

Figure 8-12: Program Version Identification Entry Format (Entry Type 6) 







SYMBOL 
NAME 





6 









8.1.1.8 Mapped Array Declaration (Entry Type 7) — The mapped array declara- 
tion (see Figure 8-13) allocates space within the mapped array area of the 
job's memory. The linker adds the array name to the hst of p-sect names, 
and subsequent RLD blocks can reference it. The linker adds the length (in 
units of 32-word blocks) to the job's mapped array allocation. It rounds up 
the total amount of memory allocated to each mapped array to the nearest 
256-word boundary. The contents of the flag byte are reserved and assumed 
to be zero. (Only the FORTRAN IV compiler produces this VSECT.) 

The Unker processes a VSECT as a PSECT with the following attributes: 

.PSECT . VIR.,RW,D,GBL,REL,CON 

The size is equal to the number of 32-word blocks required. If the length is 
zero, the segment is the root. There must never be any globals under this 
section, which starts at a base of 0. 



NOTE 

One additional address window is allocated whenever a 
mapped array is declared. 

Figure 8-13: Mapped Array Declaration Entry Format (Entry Type 7) 



MAPPED ARRAY 
NAME 



RESERVED 



LENGTH 
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8.1.2 End of Global Symboll Directory Block (ENDGSD) 

The end of global symbol directory block (see Figure 8-14) declares that no 
other GSD blocks are containcid in this module. Exactly one end of GSD 
block must appear in every obj ect module. The length of the data block is 
one viTord. 

Figure 8-14: End of GSD Data Block 






DATA BLOCK CODE 
(ENDGSD = 2) 



8.1.3 Text Information Block (TXT) 

The text information block (see Figure 8-15) contains a byte string of infor- 
mation that the linker writes directly into the output file. The block con- 
sists of a load address followed by the byte string. 

Text records can contain words or bytes of information whose final con- 
tents have not yet been determined. This information wiU be bound by a 
relocation directory block that immediately follows the text block. If the 
text block does not need modifiication, then no relocation directory block is 
needed. Thus, multiple text blocks can appear in sequence before a reloca- 
tion directory block. 

The load address of the text block is specified as an offset from the current 
p-sect base. At least one relocsition directory block must precede the first 
text block. This RLD block must declare the current p-sect. 

Figure 8-15: Text Information Data Block 






DATA BLOCK CODE 
(TXT = 3) 


LOAD 


ADDRESS 


TEXT 


TEXT 


TEXT 


TEXT 


TEXT 


TEXT 



TEXT 


TEXT 


TEXT 


TEXT 


TEXT 


TEXT 
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8.1.4 Relocation Directory Biocic (RLD) 

Relocation directory blocks (see Figure 8-16) contain the information the 
linker needs to relocate and link the preceding text information block. 
Every module must have at least one relocation directory block that 
precedes the first text information block. The first block does not modify a 
preceding text block. Instead, it defines the current p-sect and location. 

Figure 8-16: Relocation Directory Data Block 






DATA BLOCK CODE 
(RLD=4) 


DISPLACEMENT 


COMMAND 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


• 
• 
• 


COMMAND 


INFORMATION 


INFORMATION 


DISPLACEMENT 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


DISPLACEMENT 


COMMAND 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 


INFORMATION 



Relocation directory blocks can contain 14 types of entries. These entries 
are classified as relocation, or location modification entries. Table 8-5 lists 
the valid entry types. 

Each type of entry is represented by a command byte, which specifies the 
type of entry and the word or byte modification. This byte is followed by a 
displacement byte and then by the information required for the particular 
type of entry. The displacement byte, when added to the value calculated 
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Tablt! 8-5: Valid Entry Types jfor RLD Blocks 

Entry Type Description 



1 Internal Relocation 

2 Global Relocation 

3 Internal Disjplaced Relocation 

4 Global Displaced Relocation 

5 Global Additive Relocation 

6 Global Addi(;ive Displaced Relocation 

7 Location Counter Definition 

10 Location Cotinter Modification 

11 Program Limits (.LIMIT) 

12 P-sect Relocation 

13 Not used 

14 P-sect Displaced Relocation 

15 P-sect Additive Relocation 

16 P-sect Additive Displaced Relocation 

17 Complex Relocation 



from the load address of the preceding text information block, yields the 
virtual address in the image that is to be modified. The command byte of 
each entry has the bit assignmcmts shown in Table 8-6. The following sec- 
tions describe the valid entry types for the RLD data block. 

Table 8-6: Bit Assignments foii- the RLD Command Byte 
Bit Meaning 

0-6 Specify the type of entry. Although there is room to specify 128 com- 

mand types, only 14 decimal are currently implemented in the RT-11 
linker. 

7 Modification (the B bit in Figures 8-17 through 8-30). This feature is not 

supported by RT-11, and the bit is ignored if set. The RT-Il linker sup- 
ports word relocation, not byte relocation. 

= The command modifies an entire word. 

1 = The command modifies only one byte. 



8.1.4.1 Internal Relocation (Entry Type 1) — This type of entry (see Figure 
8-17) relocates a direct pointer to an address within a module. The linker 
adds the current p-sect base ad<iress to a specified constant and writes the 
result into the output file at the calculated address — that is, it adds a 
displacement byte to the value calculated from the load address of the 
preceding text block. 
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For example: 

A: MOV #A,RO 

or 

.WORD A 

Figure 8-17: Internal Relocation (Entry Type 1) 



DISPLACEMENT 



CONSTANT 



8.1.4.2 Global Relocation (Entry Type 2) — This type of entry (see Figure 8-18) 
relocates a direct pointer to a global symbol. The linker obtains the defini- 
tion of the global symbol and writes the result into the output file at the 
calculated address. 

For example: 

MOV #GLOBAL,R0 



or 



.WORD GLOBAL 



Figure 8-18: Global Relocation (Entry Type 2) 



DISPLACEMENT B 



SYMBOL 
NAME 



8.1.4.3 Internal Displaced Relocation (Entry Type 3) — This type of entry (see 
Figure 8-19) relocates a relative reference to an absolute address from 
within a relocatable control section. The linker subtracts from the specified 
constant the address plus 2 into which the relocated value is to be written. 
The linker then writes the result into the output file at the calculated ad- 
dress. 



For example: 

GLR 177550 



or 



MOV 1 77550, RO 



8-16 File Formats 



Figure 8-19: Internal Displaced Relocation (Entry Type 3) 



DISPLACEMENT B 



CONSTANT 



8.1.4.4 Global Displaced Relocation (Entry Type 4) — This type of entry (see 
Figure 8-20) relocates a relative reference to a global symbol. The linker ob- 
tains the definition of the global symbol, and subtracts from the definition 
value the address plus 2 into which the relocated value is to be written. It 
then writes the result into the output file at the calculated address. 

For example: 

CLR GLOBAL 



or 



MOV GLOBAURO 



Figure 8-20: Global Displaced Relocation (Entry Type 4) 



DISPLACEMENT B 



SYMBOL 
NAME 



8.1.4.5 Global Additive Relocatiion (Entry Type 5) — This type of entry (see 
Figure 8-21) relocates a direct pointer to a global symbol with an additive 
constant. The linker obtains the definition of the global, adds the specified 
constant, and then writes the resultant value into the output file at the 
calculated address. 

For example: 

MOV #GLOBAL + 2,R0 



or 



.WORD GLOBAL -4 



Figure 8-21: Global Additive Relocation (Entry Type 5) 



DISPLACEMENT B 



SYMBOL 
NAME 



CONSTANT 
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8.1.4.6 Global Additive Displaced Relocation (Entry Type 6) — This type of entry 
(see Figure 8-22) relocates a reference to a global symbol with an additive 
constant. The linker obtains the definition of the global symbol and adds 
the specified constant to the definition value. The linker subtracts from the 
resultant additive value the address plus 2 into which the relocated value is 
to be written. It then writes the result into the output file at the calculated 
address. 

For example: 

CLR GLOBAL +2 



or 



MOV 



GLOBAL -5,R0 



Figure 8-22: Global Additive Displaced Relocation (Entry Type 6) 



DISPLACEMENT 



SYMBOL 
NAME 



CONSTANT 



8.1.4.7 Location Counter Definition (Entry Type 7) — This type of entry (see 
Figure 8-23) declares a current p-sect and location counter value. The linker 
stores the control base as the current control section. It adds the current 
control section base to the specified constant and stores the result as the 
current location counter value. 

Figure 8-23: Location Counter Definition (Entry Type 7) 



SECTION 
NAME 



CONSTANT 



8.1.4.8 Location Counter Modification (Entry Type 10) — This type of entry (see 
Figure 8-24) modifies the current location counter. The linker adds the cur- 
rent p-sect base to the specified constant and stores the result as the cur- 
rent location counter. 
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For example: 

. = . + N 



or 



.BLKB N 



Figure 8-24: Location Counteir Modification (Entry Type 10) 



10 



CONSTANT 



8.1.4.9 Program Limits (Entry Type 11)— The .LIMIT assembler directive 
generates this type of entry (see Figure 8-25). The linker obtains the first 
address above the header, which is normally the beginning of the stack, and 
the highest address allocated to the job. It then writes these addresses into 
the output file at the calculated address and the following location, respec- 
tively. 

For example: 

.LIMIT 

Figure 8-25: Program Limits (Entry Type 11) 



DISPLACEMENT 


B 


11 



8.1.4,10 P-sect Reiocation (Entry Type 12) — This type of entry (see Figure 
8-26) relocates a direct pointer to the beginning address of another p-sect 
(other than the p-sect in which, the reference is made) within a module. The 
link(5r obtains the current bast! address of the specified p-sect and writes it 
into the output file at the calculated address. 

For example: 

.PSECT A 
B: 



.PSECT 
MOV 



C 
#B,RO 



or 



.WORD B 
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Figure 8-26: P-sect Relocation (Entry Type 12) 



DISPLACEMENT B 



12 



SECTION 
NAME 



8.1.4.11 P-sect Displaced Relocation (Entry Type 14) — This type of entry (see 
Figure 8-27) relocates a relative reference to the beginning address of 
another p-sect within a module. The linker obtains the current base address 
of the specified p-sect. It then subtracts from the base value the address 
plus 2 into which the relocated value is to be written and writes the result 
into the output file at the calculated address. 

For example: 

.PSECT A 



PSECT C 
MOV B,RO 

Figure 8-27: P-sect Displaced Relocation (Entry Type 14) 



DISPLACEMENT 



14 



SECTION 
NAME 



8.1.4.12 P-sect Additive Relocation (Entry Type 15) — This type of entry (see 
Figure 8-28) relocates a direct pointer to an address in another p-sect 
within a module. The linker obtains the current base address of the 
specified p-sect. It adds the base to the specified constant and then writes 
the result into the output file at the calculated address. 

For example: 

.PSECT A 
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or 



.PSECT D 

MOV #B + 10,R0 

MOV #C,RO 



.WORD B + 10 
.WORD C 



Figure 8-28: P-sect Additive Relocation (Entry Type 15) 



DISPLACEMENT 



15 



SECTION 

NAME 



CONSTANT 



8.1.4.13 P-sect Additive Displaced Relocation (Entry Type 16) — This type of en- 
try [see Figure 8-29) relocatesi a relative reference to an address in another 
p-sect within a module. The linker obtains the current base address of the 
specified p-sect and adds it to the specified constant. Next, it subtracts 
from the resultant additive value the address plus 2 into which the 
relocated value is to be written. It writes the final result into the output file 
at the calculated address. 

For example: 

.PSECT A 
B: 



.PSECT D 

MOV B + IO.RO 

MOV C.RO 



Figiare 8-29: P-sect Additive Displaced Relocation (Entry Type 16) 



DISPLACEMENT 



16 



SECTION 
NAME 



CONSTANT 
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8.1.4.14 Complex Relocation (Entry Type 17) — This type of entry (see Figure 
8-30) resolves a complex relocation expression. A complex relocation expres- 
sion is one in which any of the MACRO- 11 binary or unary operations are 
permitted with any type of argument, regardless of whether the argument is 
unresolved global, relocatable to any p-sect base, absolute, or a complex relo- 
catable subexpression. 

The RLD command word is followed by a string of numerically specified 
operation codes and arguments. The operation codes each occupy one byte 
and the entire RLD command must fit in a single data block. Table 8-7 shows 
the list of valid operation codes. Note that complex relocation on foreground 
links causes a warning message from the linker. The results of complex reloca- 
tion will be correct if no relocatable symbols are involved, however. 

Table 8-7: Operation Codes for Complex Relocation 
Code Description 

No operation 

1 Addition ( + ) 

2 Subtraction ( - ) 

3 Multiplication (*) 

4 Division (/) 

5 Logical AND (&) 

6 Logical inclusive OR (!) 

7 Exclusive OR 

10 Negation ( - ) 

11 Complement ('^C) 

12 Store result (command termination) 

13 Store result with displaced relocation (command termination) 

16 Fetch global symbol. It is followed by four bytes containing the symbol 
name in Radix-50 representation. 

17 Fetch relocatable value. It is followed by one byte containing the sector 
number, and two bytes containing the offset within the sector. 

20 Fetch constant. It is followed by two bytes containing the constant. 

The STORE commands (codes 12 and 13) indicate that the value is to be 
written into the output file at the calculated address. 

The linker evaluates all operands as 16-bit signed quantities using two's 
complement arithmetic. The results are equivalent to expressions that are 
evaluated internally by the assembler. Note the following rules. 

1. An attempt to divide by yields a result. The linker issues a warning 
message. 

2. All results are truncated from the left in order to fit into 16 bits. No 
diagnostic is issued if the number was too large. If the result modifies a 
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byte, the linker checks for truncation errors. (Byte operations are not 
allowed.) 

3. All operations are perforaed on relocated (additive) or absolute 16-bit 
quantities. PC displacement is applied to the result only. 

For example: 

.PSECT ALPHA 
A: 



.PSECT BETA 
B: 



MOV #A + B -<G1/G2&-C < 177120IG3 » ,R1 



Figure 8-30: Complex Relocation (Entry Type 17) 



DISPLACEMENT 


B 


17 


COMPLEX STRING 


12 





8.1. J5 Internal Symbol Directory Block (ISD) 

Internal symbol directory blocks (see Figure 8-31) declare definitions of 
symbols that are local to a module. The linker does not support this feature; 
therefore, a detailed data block format is not documented here. If the linker 
encounters this type of data b»lock, it ignores it, 

Figure 8-31: Internal Symbol Directory Data Block 






DATA BLOCK CODE 
(ISD = 5) 


NOT SPECIFIED 



8.1.6 End of Module Block (ENDMOD) 

The end of module block (see Figure 8-32) declares the end of an object 
modiule. Exactly one end of module record must appear in each object 
modiule. It is one word long. 
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Figure 8-32: End of Module Data Block 






DATA BLOCK CODE 
(ENDM0D = 6) 



8.2 Symbol Table Definition File Format (STB) 

The RT-11 linker can produce a symbol table (STB) file as its third output 
file. The text of the STB file consists of global symbol table definitions. For 
example, if the source file contains X = = 10, the STB file contains X = 10. 
Or, if the source file contains A = FOO, the STB file contains the address of 
FOO. 

The STB file can serve as a communication link between a background and 
a foreground job. This communication comes about when you link the back- 
ground job and obtain an STB file as output. Then, when you link the fore- 
ground job, include the STB file as one of the input files. The foreground job 
will then be able to reference symbols used by the background job. Sim- 
ilarly, you can use the STB file to create a communication link between a 
program and a symbolic debugger. 

The internal format of the STB file consists entirely of Global Symbol 
Directory (GSD) data blocks followed by one End of Global Symbol Direc- 
tory (ENDGSD) data block and one End of Module (ENDMOD) data block. 
Figure 8-33 illustrates the STB file format. 

Figure 8-33: STB File Format 



MODULE NAME ENTRY 
(GSD TYPED) 



OPTIONAL 

PROGRAM VERSION IDENTIFICATION ENTRY 

(GSD TYPE 6) 



CONTROL SECTION NAME ENTRY 

(GSD TYPE 1) 

A ZERO-LENGTH CSECT WITH NAME . ABS. 



GLOBAL SYMBOL NAME ENTRIES 

(GSD TYPE 4) 

THESE ARE ALL ABSOLUTE AND CONTAIN 

ONLY DEFINITIONS 



ENDGSD DATA BLOCK 



ENDMOD DATA BLOCK 
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8.3 Library File Format (OBJ and l\/IAC) 

A lilbrary file contains concateinated modules and some additional informa- 
tion. RT-11 supports object and macro libraries. Object libraries usually 
have an .OBJ file type; macroi libraries usually have a .MAC file type. 

The modules in an object or macro Ubrary file are preceded by a Library 
Header Block and Library Duectory, and are followed by the Library End 
Block, or trailer. Figure 8-34 shows the format of an object or macro library 
file. 



Figure 8-34: Library File Format (OBJ and MAC) 



LIBRARY HEADER 



DIRECTORY 



CONCATENATED MODULES 
(STARTS ON A BLOCK BOUNDARY) 



LIBRARY END TRAILER BLOCK 



Diagrams of each component in the Ubrary file structure are included in the 
sections that follow. See the RT-11 System User's Guide for information on 
using the librarian. 

8.3.11 Library Header Format 

The library header describes the status of the file. Of the two figures that 
follow, Figure 8-35 shows the contents of the object Ubrary header and 
Figure 8-36 shows the contents of the macro Ubrary header. 

All numeric values shown are octal. The date and time, which are in stan- 
dard RT-11 format, are the date and time the Ubrary was created. This in- 
formiation is displayed when the Ubrary is Usted. 

8.3.2 Library Directories 

There are two kinds of Ubrary directories: for object Ubraries, the directory 
is an Entry Point Table (EPT); for macro Ubraries, the directory is a Macro 
Name Table (MNT). The EFT directory (see Figure 8-37) consists of four- 
word entries that contain information related to aU modules in the Ubrary 
file. 



File Formats 8-25 



Figure 8-35: Object Library Header Format 



OFFSET 


CONTENTS 


DESCRIPTION 





1 


LIBRARY HEADER BLOCK CODE 


2 


42 




4 


7 


LIBRARIAN CODE 


6 


310 


LIBRARY VERSION NUMBER 


10 





RESERVED 


12 




DATE IN RT-1 1 FORMAT (0 IF NONE) 


14 




TIME EXPRESSED IN TWO WORDS 


16 




20 





1 IF LIBRARY CREATED WITH /X OPTION 


22 





RESERVED 


24 





RESERVED 


26 


10 


DIRECTORY RELATIVE START ADDRESS 


30 




NUMBER OF BYTES IN DIRECTORY 


32 





RESERVED 


34 




NEXT INSERT RELATIVE BLOCK NUMBER 


36 




NEXT BYTE WITHIN BLOCK 


40 




DIRECTORY STARTS HERE 



Note that if you use the librarian /N option for object libraries to include 
module names, bit 15 of the relative block number word is set to 1. If you in- 
voke the librarian with the monitor LIBRARY command, module names 
are never included. 

In the Ubrary directory, the symbol characters represent the entry point or 
the macro name. The relative byte maximum is 777 octal. 

The object library directory starts on the first word after the library header, 
word 40 octal. The object library directory is only long enough to accom- 
modate the exact number of modules in the library and space for this direc- 
tory is not pre-allocated. The directory is kept in memory during librarian 
operations, and the amount of available memory is the only limiting factor 
on the maximum size of the directory. Reserved locations in the header and 
at the end of the directory — those not used by the directory — are zero- 
filled. Modules follow the directory and they are stored beginning in the 
next block after the directory. 

The macro library directory starts on a block boundary, relative block 1 of 
the library file. Its size is pre-allocated. The default size is two blocks but 
you can change this by using the librarian /M option. Unused entries in the 
directory are filled with - 1. Macro files are stored starting on the block 
boundary after the directory. This is relative block 3 of the library file if you 
use the default directory size. 
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Figure 8-36: Macro Library FEeader Format 



OFFSET 


CONTENTS 


DESCRIPTION 





1001 


LIBRARY TYPE AND ID CODE 


2 


310 


LIBRARY VERSION NUMBER 


4 





RESERVED 


6 




DATE IN RT-1 1 FORMAT (0 IF NONE) 


110 




TIME EXPRESSED IN TWO WORDS 


12 




14 





RESERVED 


16 





RESERVED 


20 





RESERVED 


22 





RESERVED 


24 





RESERVED 


26 





RESERVED 


•!0 





RESERVED 


32 


10 


SIZE OF DIRECTORY ENTRIES 


34 




DIRECTORY STARTING RELATIVE BLOCK NUMBER 


36 




NUMBER OF DIRECTORY ENTRIES ALLOCATED 
(DEFAULT IS 200) 


40 




NUMBER OF DIRECTORY ENTRIES AVAILABLE 



Figure 8-37: Library Directory Format (OBJ) 



SYMBOL CHARACTERS 1-3 (RADIX-50) 


SYMBOL CHARACTERS 4-6 (RADIX-50) 




BLOCK NUMBER RELATIVE TO START OF FILE 


RESERVED 
(7 BITS) 


RELATIVE BYTE IN BLOCK 
OBITS) 



Modules in libraries are concatenated by byte. (See Figure 8-2 for an exam- 
ple of byte concatenation.) This means that a module can start on an odd ad- 
dress. When this occurs, the linker shifts the module to an even address at 
link time. 



8.3.3 Library End Block Format 

Following all modules in an object or macro library is a specially coded 
Library End Block, or trailer, which signifies the end of the file (see Figure 
8-38). 
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Figure 8-38: Library End Block Format 



10 



10 



357 



DATA BLOCK HEADER 
DATA BLOCK LENGTH 

LIBRARY END BLOCK CODE 
RESERVED, MUST BEG 
CHECKSUM BYTE 



8.4 Absolute Binary File Format (LDA) 

Both the linker /L option and the keyboard monitor LINK command /LDA 
option produce output files in a paper tape-compatible binary format. 

Absolute binary format, shown in Figure 8-39, consists of a sequence of 
data blocks, where each block represents the data to be loaded into a 
specific portion of memory. The data portion of each block consists of the 
absolute load address of the block, followed by the absolute data bytes to be 
loaded into memory beginning at the load address. There can be as many 
data blocks as necessary in an LDA file. The last block of the file is special 
because it contains only the program start address, or transfer address, in 
its data portion. If this address is even, the Absolute Loader passes control 
to the loaded program at this address. If it is odd (that is, if the program has 
no transfer address, or the transfer address was specified as a byte bound- 
ary), the loader halts upon completion of loading. The final block of the 
LDA file is recognized by the fact that its length is six bytes. 

You can use LDA format files for down-line loading of programs, for loading 
stand-alone application programs, and as input to special programs that 
put code into ROM (Read-Only Memory). The general procedure for loading 
a program that will execute in a stand-alone environment is as follows: 

1. Toggle the Bootstrap Loader into memory. 

2. Using the Bootstrap Loader, load the Absolute Loader into memory. 

3. Using the Absolute Loader, load the LDA file into memory and begin 
execution. 

LSI-11 and LSI-11/2 computer systems have console microcode that makes 
steps 1 and 2 of this procedure unnecessary. The procedure for loading stand- 
alone programs is described in the Microcomputer Processor Handbook. 
LSI-11/23 computer systems do not have bootstrap loader microcode and 
require the use of steps 1 and 2. 

You can obtain a listing of the PDP-11 Bootstrap Loader from DIGITAL'S 
Software Distribution Center. Its order number is DEC-11-LlPA-LA 
(November 11, 1970). The Bootstrap Loader is also printed on the PDP-11 
Programming Card, which is part of every RT-11 distribution kit. You can 
obtain a listing of the PDP-11 Absolute Loader by ordering product 
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March 1981 



Figure 8-39: Absolute Binary Format (LDA) 

FIRST DATA BLOCK 



BCL 



BCH 



ADL 



ADH 



DATA BYTES 



CHECKSUM BYTE 



LOW-ORDER EIGHT BITS OF BYTE COUNT 

HIGH-ORDER EIGHT BITS OF BYTE COUNT 

LOW-ORDER BYTE OF ABSOLUTE LOAD ADDRESS 
OF DATA BYTES IN THE BLOCK 

HIGH-ORDER BYTE OF LOAD ADDRESS 



INTERMEDIATE DATA BLOCKS 



BCL 



BCH 



ADL 



ADH 



DATA BYTES 



CHECKSUM BYTE 



THIS PATTERN IS REPEATED FOR ALL 
INTERMEDIATE BLOCKS . 



LAST DATA BLOCK 


1 





6 





JL 


JH 


CHECKSUM BYTE 



LOW BYTE OF START ADDRESS, OR ODD NUMBER 
HIGH BYTE OF START ADDRESS, OR ODD NUMBER 
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number DEC-11-UABLA-A-LA (June 1975). A paper tape of the Ab- 
solute Loader is also available. It is called the Non-switch Register PDP-11 
Absolute Loader VB07.00, order number DEC-11-UABLB-A-PO (1975). 

Complete procedures for using the Bootstrap Loader and the Absolute 
Loader are provided in the PDP-11 Paper Tape Software Handbook, order 
number DEC-11-XPTSA-B-D (April, 1976). Appendix F contains listings 
of the Bootstrap and Absolute Loaders. 

The load module's data blocks contain only absolute binary load data and 
absolute load addresses. AU global references have been resolved and the 
linker has performed the appropriate relocation. 

8.5 Save Image File Format (SAV) 

Save image format is for programs that are to be run in the SJ environment, 
or in the background in the FB and XM environments. It is also for virtual 
jobs that are to be FRUN or SRUN in XM environments. Save image files 
normally have a .SAV file type. This format is an image of the program ex- 
actly as it would appear in memory. (Block — the first 256-word unit — of 
the file corresponds to memory locations 0-776, block 1 to locations 
1000-1776, and so on.) See Table 8-8 for the contents of block of a .SAV 
file. (Note that not all locations are used for each link; for example, whether 
the job is for an XM environment or whether it is overlaid affect block 0.) 
See also Chapter 11 of the RT-11 System User's Guide for more informa- 
tion on the load modules created by the linker. 



Table 8-8: Information in Block 

Offset 



Contents 



VIR in Radix- 50 if the linker A'^ option was used 

2 Virtual high limit if linker A'^ option was used 

4 Reserved 

6 Reserved 

10 Reserved 

12 Reserved 

14 BPT trap (XM only) 

16 BPT trap (XM only) 

20 lOT trap (XM only) 

22 lOT trap (XM only) 

24 Reserved 

26 Reserved 

30 Reserved 

32 Reserved 

34 Trap vector (TRAP) 
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Table 8-8: Information in Block (Cont.) 

Offset Contents 



36 


Trap vector (TRAF') 


40 


Program's relative start address 


42 


Initial location of stack pointer (changed by /M option) 


44 


Job Status Word 


46 


USR swap address 


50 


Program's high limit 


52 


Size of program's root segment, in bytes (used for REL files only) 


54 


Stack size, in bytes (changed by /R:n option) (used for REL files only) 


56 


Size of overlay region, in bytes (0 if not overlaid) (used for REL files only) 


60 


REL file ID {REL in Radix-50) (used for REL files only) 


62 


Relative block numiber for start of relocation information (used for REL 




files only) 


64 


Address of overlay handler table for overlaid files 


66 


Address of start oi window definition blocks (if A'' used) 


70-356 


Reserved 


360-377 


Bitmap area 



Locations 360-377 in block of the file are restricted for use by the system. 
The Unker stores the program memory usage bits in these eight words, 
which are called a bitmap. Elach bit represents one 256-word block of 
memory and is set if the program occupies any part of that block of 
memory. Bit 7 of byte 360 corresponds to locations through 777; bit 6 of 
byte 360 corresponds to locations 1000 through 1777, and so on. The 
monitor uses this information when it loads the program. 

The monitor commands R and RUN load and start a program stored in a 
SAV file. (The RUN command is actually a combination of the GET and 
START commands.) First, the Keyboard Monitor reads block of the SAV 
file into an internal USR buffer. It extracts information from locations 
40-64 and 360-377 (the bitmap, described above). Using the protection bit- 
map (called LOWMAP), which resides in RMON, KMON checks each word 
in block of the file. It does not load locations that are protected, such as 
location 54 and the device interrupt vectors. It loads unprotected locations 
into memory from the USR buffer. Next, KMON sets location 50 to the top 
of usable memory, or to the top of the user program, whichever is greater. 

If the RUN command (or the GET command) was issued, KMON checks 
the bitmap from locations 360-377 of the SAV file. For each bit that is set, 
it loads the corresponding block of the SAV file into memory. However, if 
KMON is in memory space that the program needs to use, KMON puts the 
block of the SAV file into a USR buffer and then moves it to the file 
SWAP.SYS. 



File Formats 8-31 



Finally, when it is time to begin execution of the program, KMON transfers 
control to RMON. RMON reads the parts of the program, if any, that are 
stored in SWAP.SYS into memory, where they overlay KMON and 
possibly the USR. If the R command was issued, KMON does not check the 
bitmap to see which blocks of the SAV file to load. Instead, it jumps to 
RMON and attempts to read all locations above 1000 up to the top of the 
root segment into memory. (The R command does not use SWAP.SYS.) The 
monitor keeps track of the fact that KMON and the USR are swapped out, 
and execution of the program begins. 

8.6 Relocatable File Format (REL) 

To Unk a foreground job, use the linker /R option or the keyboard monitor 
LINK command with the /FOREGROUND option. This causes the Unker 
to produce output in a linked, relocatable format, with a .REL file type. 
Note that system jobs axe also stored in relocatable format. The only dif- 
ference is that system jobs use a file type of .SYS instead of .REL. 

The object modules used to create a REL file are Unked as if they were a 
background SAV image, with a base of 1000. This permits you to use 
.ASECT directives to store information in locations through 777 in REL 
files. All global references have been resolved. The Unker does not relocate 
the REL file at link time; it merely includes relocation information to be 
used at FRUN time. The relocation information in the file is used to deter- 
mine which words in the program must be relocated when the job is in- 
stalled in memory. 

There are two types of REL files to consider: those programs with overlay 
segments, and those without them. 

8.6.1 REL Files Without Overiays 

A REL file for a program without overlays appears as shown in Figure 
8-40. 

Figure 8-40: REL File Without Overlays 



BLOCK 



PROGRAM 
TEXT 


RELOCATION 
INFORMATION 



Block (relative to the start of the file) contains the information shown in 
Table 8-8. Some of this information is used by the FRUN processor. 

In the case of a program without overlays, the FRUN processor performs 
the following general steps to install a foreground job. 

1. It reads block of the file into an internal monitor buffer. 



8-32 File Formats 



2. It obtains the amount of memory required for the job from location 52 
of block of the file, and! allocates the space in memory by moving 
KMON and the USR down. 

3. It reads the program text into the allocated space. 

4. It reads the relocation information into an internal buffer. 

5. It relocates the locations indicated in the relocation information area 
by adding or subtracting the relocation quantity. This quantity is the 
steirting address the job occupies in memory, adjusted by the reloca- 
tion base of the file. REL files are linked with a base of 1000. 

The relocation information cojasists of a list of addresses relative to the 
start of the user's program. The monitor scans the list, and for each relative 
address computes an actual address. That address is then loaded with its 
original contents plus or minus the relocation constant. The relocation in- 
formation is shown in Figure 8-41. 

Figure 8-41: Root Relocation information Format 

15 14 





RELATIVE WORD OFFSET 


ORIGINAL CONTENTS 




RELATIVE WORD OFFSET 


0RI(3INAL CONTENTS 




• 


• 




• 


• 


-2 



In Figure 8-41 bits through 14 represent the relative address to relocate 
divided by 2. This implies that; relocation is always done on a word boun- 
dary, which is indeed the case. ]3it 15 indicates the type of relocation to per- 
form — positive or negative. Tlie relocation constant (which is the load ad- 
dress of the program) is added to or subtracted from the indicated location 
depending on the sense of bit 15; implies addition, while 1 implies subtrac- 
tion. A full 16-bit word is the original contents. The value 177776, or - 2, 
terminates the Ust of relocatioii information for a file without overlays. 



File Formats 8-33 



8.6.2 REL Files with Overlays 

When you include overlays in a program, in addition to relocating the root 
segment, the FRUN processor must also relocate the overlay segments. 
Since overlays are not permanently memory resident but are read in from 
the file as needed, they require an additional operation. FRUN relocates 
each overlay segment and rewrites it into the file before the program begins 
execution. Thus, when the overlay is called into memory during program ex- 
ecution, it is correct. This process takes place each time you run an overlaid 
file with FRUN or SRUN. The relocation information for overlaid files con- 
tains both the list of addresses to be modified and the original contents of 
each location. This allows the file to be executed again after the first usage. 
It is necessary to preserve the original contents in case some change has oc- 
curred in the operating environment. Examples of these changes include us- 
ing a different monitor version, running on a system with a different 
amount of memory, and having a different set of device handlers or system 
jobs resident in memory. Figure 8-42 shows a REL file with overlays. 

In the case of a REL file with overlays, location 56 of block of the REL file 
contains the size in bytes of all the overlay regions, FRUN adds this size to 
the size of the program base segment (in location 52) to allocate space for 
the job. 

After FRUN relocates the program base (root) code, it reads each existing 
overlay into the program overlay region in memory, relocates it using the 
overlay relocation information, and then writes it back into the file. 

The root relocation information section is terminated with a - 1. This - 1 is 
also an indication that an overlay segment relocation block follows. 

The relocation is relative to the start of the program and is interpreted as if 
it were in a file without overlays (that is, bit 15 indicates the type of reloca- 
tion, and the displacement is the true displacement divided by 2). En- 
countering - 1 indicates that a new overlay region begins here; a - 2 in- 
dicates the termination of aU relocation information. 



8.7 Stream ASCII File Format 



Source files, such as MACRO- 11 and FORTRAN IV programs, and text 
files that you create with an editor are in stream ASCII format. These files 
consist of a series of bytes, each byte representing an ASCII character. 
Stream ASCII files have no special headers or end blocks, nor do they in- 
clude any formatted binary blocks. 

An ASCII 32, or CTRL/Z character, may terminate a stream ASCII file. 
When you invoke PIP with the /A option (or when you use the monitor 
COPY/ASCII command) to copy an ASCII file, PIP expects to find a 
CTRL/Z at the end of the file. If there is an embedded CTRL/Z character 
within the file, PIP considers the CTRL/Z to mark the file's end. When you 
invoke PIP in its default mode (or when you use the monitor COPY com- 
mand without any option) to copy an ASCII file, PIP does not look for a 
CTRL/Z character. It simply continues copying until it reaches the end of 
the file. 
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Figure 8-42: REL File with Overlays 



BLOCK 



ROOT 

SEGMENT 

TEXT 



OVERLAY 
1 DATA 



OVERLAY 
N DATA 



REL CONTROL BLOCK 

OVERLAY HANDLER AND TABLES 



ROOT RELOCATION INFORMATION 
(AS SHOWN IN FIGURE 8-41) 



END OF ROOT RELOCATION INFORMATION 

OVERLAY SEGMENT 1 RELOCATION INFORMATION 
(AS SHOWN IN FIGURE 8-43) 

END OF OVERLAY 1 RELOCATION INFORMATION 



OVERLAY SEGMENT N RELOCATION INFORMATION 
(AS SHOWN IN FIGURE 8-43) 

IF EXTRA ROOT INFORMATION, 
SUCH AS RELOCATING 
OVERLAY HANDLER INFORMATION 
(AS SHOWN IN FIGURE 8-43) 

END OF ALL RELOCATION INFORMATION 



8.8 CREF File Format 



The RT-11 CREF program produces a cross-reference listing. You can only 
run CREF indirectly — that" is, by chaining to it from another program, 
such as your own language pirocessor. CREF appends its cross-reference 
tabkj to the hsting file your calling program creates. 

To chain to CREF, you must first store some information in the chain com- 
munication area (absolute locations 500 through 776) of the calling pro- 
gram. Table 8-9 lists the information that CREF requires. 
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Figure 8-43: Overlay Segment Relocation Block 



OVERLAY BLOCK NUMBER 



OVERLAY SIZE 



RELATIVE WORD OFFSET 



TEXT TO RELOCATE 



RELATIVE WORD OFFSET 



TEXT TO RELOCATE 



START OF OVERLAY RELATIVE TO START OF FILE 
(VALUE ISO IF THIS IS 
EXTRA ROOT INFORMATION) 

SIZE OF OVERLAY IN WORDS 
(VALUE IS OIF THIS IS 
EXTRA ROOT INFORMATION) 



RELATIVE WORD OFFSET 



TEXT TO RELOCATE 



Table 8-9: CREF Chain Interface Specification 

Location Contents Description 



500 


.RAD50/SY / 


502 


.RAD50 /CRE/ 


504 


.RAD50 /F / 


506 


.RAD50 /SAV/ 


510 




512 




514 




516 




520 




522 




524 




526 


.RAD50 /dev/ 


530 


.RAD50 /fil/ 


532 


.RAD50 /nam/ 


534 


.RAD50 /typ/ 


536-776 





The file specification to invoke CREF: 



RT-11 channel number of output file 

Radix-50 name of output device 

Highest output block number written, plus 1 

RT-11 channel number of input file 

Radix-50 name of input device 

Highest input block number written, plus 1 

Listing format: = 80 colunms, - 1 = 132 

Program to chain back to. (If this value is zero, 
CREF closes the listing file and exits.) 



ASCIZ string for CREF to use as title Une (no 
page number) 
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The input file you supply to C/REF must consist of 12-byte decimal entries, 
one entry for each reference to a symbol. Table 8-10 shows the format of the 
entries. 



Table 8-10: Entry Format for CREF Input File 

Octal Value 

Byte Offset 



Section descriptor: 

Bits through 4 contain an alphabetic character for 
CREF to use as the section name. The ASCII value 
is stripped to 5 bits. 

Bits 5 through 7 contain the section number. This 
number controhi the order of the sections. 

1-6 The ASCII name of the symbol. 

7-10 The page number, in binary. Put - 1 here if you are 

not using page numbers. 

11-12 The line number, in binary. 

13 A one-character identifier for CREF to print next to 

this reference. Typically, this character is used to 
identify a destinictive reference or a definitional 
reference. 



8.9 Error Log File Formats 



Device handlers that support error logging call the error logger through a 
monitor pointer on each successful I/O transfer as well as on each error. The 
copy code in the error logger retrieves, or copies, the appropriate informa- 
tion from the handler, storing it in the error log input buffer in the error log- 
ger's memory area. The error log job is suspended until the copy routine 
puts some data into the input buffer, at which point the monitor resumes 
the error log job so it can process the new data. 

The error log job remains suspended until the error log input buffer has 
filled to 200 or more words oif the 256-word decimal total buffer size. The 
copy code portion of the EL job informs the monitor of this by setting the 
carry bit on return. Thus the error log job is resumed by the monitor only 
when the error log input buffei- contains a sizeable amount of information to 
be processed. 

For device errors, cache errors, and memory parity errors, the error logger 
first; creates or updates the unit statistics information in the copy of the 
disk; file header that is in memiory. The EL job (disk output code) stores er- 
ror records in the disk output buffer (one of two buffers, since double- 
buffering is used) until a 256-word decimal block is full. That is, it stores 
records until the buffer cannot contain the next record. Then it writes the 
updated header record and tlbe accumulated error records to a disk file 
called ERRLOG.DAT. Figure 8-44 describes the error logging subsystem. 
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For successful I/O transfers, the error logger first creates or updates the 
unit statistics information in the copy of the disk file header that is in 
memory, as it does with device and memory errors. It writes the updated 
header to disk only after 10 (decimal) good I/O transfers have been logged. 

Figure 8-44: Error Logging Subsystem 



HANDLERS 

On 
O 



FRUN/SRUN EL 



6 



THROUGH 

RMON 

$ELPTR 

TO STORE ■ 

DATA INTO 

INPUT 

BUFFER 



I 



ELINIT 



EL JOB 



MONITOR 
RESUMES 
EL JOB TO 
EMPTY INPUT 
BUFFER AND 
PREPARE DATA 
FOR OUTPUT 



r 



L_ 



"COPY CODE" — 

INPUT BUFFER 

DISK OUTPUT 
CODE 

HEADER RECORD 



OUTPUT BUFFER 
1 

OUTPUT BUFFER 
2 



INITIALIZE 
ERRLOG. DAT 
FILE& 
START El. 



_l 



W-' 



ERROUT 



REPORTER 
UTILITY 




REPORT OUTPUT 



COMUNICATES 
WITH EL TO 
CAUSE ALL CURRENT 
DATA IN INPUT BUFFER 
TO BE WRITTEN OUT 
TOERRORLOG.DAT 
IN ORDER TO GIVE 
COMPLETE REPORT 



ERRORS & 
STATISTICS 



8.9.1 Error Log Input Buffer Record Format 

Figure 8-45 shows the format of the internal error log input buffer record. 
Figure 8-46 shows the record format for a successful transfer. Figure 8-47 
shows the record format for cache and memory parity errors. 

The value of parity ID in Figure 8-47 is as follows: 

- 2 for a memory error 

- 3 for a cache error 

- 4 for both memory and cache error 
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Figure 8-45: Error Log Input [Buffer Record Format for Device Error 



ENTRY NUMBER 



SIZE OF THIS RECORD 



DEVICE ID 



RETRY COUNT 



PHYSICAL BLOCK NUMBER (Q.BLKN) 



RESERVED 
(1 BIT) 



JOB 

NUMBER 
(4 BITS) 



DEVICE 
UNIT 
(3 BITS) 



SPECIAL FUNCTION 

CODE 

(8 BITS) 



USER BUFFER ADDRESS (Q.BUFF) 



WORD COUNT (Q.WCNT) 



PARI VALUE (Q.PAR) -XMONLY 



TOTAL NUMBER OF RETRIES 



NUMBER OF REGISTERS TO LOG 



the; DEVICE REGISTERS: 



Figure 8-46: Error Log Input Buffer Record Format for Successful 
Transfer 



ENTRY NUMBER 


SIZE OF THIS RECORD 


DEVICE ID 


-1 


RESERVED 
(1 BIT) 


JOB 

NUMBER 
(4 BITS) 


DEVICE 
UNIT 
(3 BITS) 


SPECIAL FUNCTION 

CODE 

(8 BITS) 


WORD COUNT (Q.WCNT) 



Figure 8-47: Error Log Input Buffer Record Format for Cache and 
Memory Parity Elrrors 



ENTRY NUMBER 



SIZE OF THIS RECORD 



NUMBER OF MEMORY REGISTERS 



PARITY ID 



PC 



PS 



MPR1 



ADDRESS OF MPR1 



(INFORMATION FOR UP TO 16 MEMORY REGISTERS:; 



MEMORY SYSTEM ERROR REGISTER (IF CACHE IS PRESENT) 



CACHE CONTROL REGISTER (IF CACHE IS PRESENT) 



HIT/MISS REGISTER (IF CACHE IS PRESENT) 
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8.9.2 Error Log Disk File Format 

The error log disk file is called ERRLOG.DAT. Figure 8-48 shows its 
format. 

The value of parity ID in Figure 8-48 is as follows: 

- 2 for a memory error 

- 3 for a cache error 

- 4 for both memory and cache error 

Figure 8-48: ERRLOG.DAT Format 



BLOCK OOF ERRLOG.DAT: (DATA STARTS IN BLOCK 1) 



POINTER TO THE HEADER SUMMARY SECTION 



DEVICE AND UNIT INFORMATION - 

(THE LENGTH OF THIS SECTION VARIES DEPENDING ON ERL$U) 

(A SEVEN-WORD ENTRY FOR EACH DEVICE UNIT LOGGED): 



DEVICE ID 



UNIT 



NUMBER OF ERROR RECORDS LOGGED 



NUMBER OF ERRORS RECEIVED 



READSUCESSES 
(TWO WORDS) 



WRITE SUCCESSES 
(TWO WORDS) 



HEADER SUMMARY SECTION 



TOTAL NUMBER OF ERRORS RECEIVED (INCLUDING OCCASIONS WHEN THE 
ERROR LOGGER WAS UNABLE TO RECORD THE ERROR INFORMATION) 



COUNT OF MISSED RECORDS (NOT RECORDED BECAUSE THE ERROR LOGGER 
INPUT BUFFERS WERE FULL) 



COUNT OF MISSED RECORDS (NOT RECORDED BECAUSE ERRLOG.DAT 
WAS FULL) 



COUNT OF MISSED RECORDS (NOT RECORDED BECAUSE START UP OR SHUT 
DOWN WAS IN PROGRESS) 



NUMBER OF MEMORY PARITY ERRORS 



NUMBER OF CACHE PARITY ERRORS 



NEXT PHYSICAL RECORD NUMBER 



BLOCK NUMBER FOR START OF NEXT RECORD 



OFFSET WITHIN THE BLOCK FOR THE NEXT RECORD 



MAXIMUM SIZE OF ERROR FILE, IN BLOCKS 



CONFIGURATION WORD 1 (MONITOR FIXED OFFSET 300) 



CONFIGURATION WORD 2 (MONITOR FIXED OFFSET 370) 
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Figure 8-48: ERRLOG.DAT F<jrmat (Cont.) 



DATi^OF INITIALIZATION 



TIME OF INITIALIZATION (TWO WORDS) 



DATA BLOCKS 

( A SERIES OF 256-WORD BLOCKS CONTAINING ERROR INFORMATION): 



FOR EACH DEVICE ERROR: 



PHYSICAL RECORD NUMBER 



SIZE OF THIS ERROR RECORD 



DEVICE ID 



UNIT 



NUMBER OR OCCURRENCES OF THIS 
ERROR WITH IDENTICAL REGISTERS 



RETRY COUNT 



DATE OF ENTRY 



TIME OF ENTRY 
(TWO WORDS) 



PHYSICAL BLOCK NUMBER (Q.BLKN) 



USER BUFFER ADDRESS (O.BUFF) 



WORD COUNT (Q.WCNT) 



PAR 1 VALUE (Q.PAR) - XM ONLY 



TOTAL NUMBER OF RETRIES 



NUMBER OF REGISTERS TO LOG 



THE DEVICE REGISTERS: 



FOR EACH PARITY ERROR: 



PHYSICAL RECORD NUMBER 



SIZE OF THIS ERROR RECORD 



NUMBER OF MEMORY REGISTERS 



PARITY ID 



NUMBER OF OCCUR RENCES OF THIS ERROR WITH THE SAME PC 



DATE OF ENTRY 



TIME OF ENTRY 
(TWO WORDS) 



PC 



PS 



MPR1 



ADDRESS OF MPR1 



(INFORMATION FOR UP TO 16 MEMORY REGISTERS:) 



MEMORY SYSTEM ERROR REGISTER (IF CACHE IS PRESENT) 



CACHE CONTROL REGISTER (IF CACHE IS PRESENT) 



HIT/MISS REGISTER (IF CACHE IS PRESENT) 
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Chapter 9 
File Storage 



RT-ll stores files under assigned file names on file-structured devices. 
RT-11 devices that are file-strvictured include all disks and diskettes, DEC- 
tapes, magtape, and cassette. 

File-structured devices that have a series of directory segments at the 
beginning of the device are caled directory-structured devices. The direc- 
tory segments contain entries describing the names, lengths, and creation 
dates of files on the device. Disks, diskettes, and DECtapes are directory- 
structured devices. Because the directory is at the beginning of the device, 
you can access any file on the device, no matter where it is located, without 
reading any other files. For tliis reason, directory-structured devices are 
sometimes called random-accesis or block-replaceable devices. 

Magtape and cassette are file-structured devices that do not have a direc- 
tory at the beginning. While they do store some directory information at 
the beginning of each file, you must still read the entire volume to obtain all 
the hiformation about all the files. Because you must read the files in order, 
one after the other, magtape and cassette are also called sequential-access 
devices. 

This chapter shows how RT-11 stores files on both random-access and 
sequential-access devices. It also describes the contents of a device direc- 
tory and shows how to recover information from a random-access device 
whose directory is corrupted. 



9.1 Random-Access Devices 



A random-access device consists of a series of 256-word blocks where blocks 
through 5 are reserved for system use and cannot be used for data 
storage. The device directory begins at block 6. Figure 9-1 shows the for- 
mat of a random-access device. 

9.1.1 Home Block 

Block 1 of a random-access device, called the home block, contains informa- 
tion about the volume and its owner. Figure 9-2 and Table 9-1 show the 
home block format and content;s. 

To compute the checksum, all the bytes are added into a word, which is then 
negated. 

The contents of all other areas ha the home block are undefined and reserved 
for future use by DIGITAL. 
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Figure 9-1: Random-Access Device 



OCTAL 
BLOCK NUMBER CONTENTS 



10 



11 



X+1 



FILES 



RESERVED 

HOME BLOCK (RESERVED) 

RESERVED 

RESERVED 

RESERVED 

RESERVED 

DIRECTORY SEGMENT 1 
DIRECTORY SEGMENT 2 



DIRECTORY SEGMENT N 



STORED DATA 



END OF DEVICE 



9.1.2 Directory Structure 

The directory consists of a series of two-block segments. Each segment is 
512 words long and contains information about files such as name, length, 
and creation date. A directory can have from 1 to 31 decimal segments. You 
establish the size of the directory area by determining at device initiaUza- 
tion time the number of segments in the directory. Use the 
INITIALIZE/SEGMENTSm command, or DUP with the /Z/N:n options. 
(See Chapter 4 of the RT-11 System User's Guide for more information on 
the INITIALIZE command and for a table of the default number of 



9-2 File Storage 



Figure 9-2: Home Block Format 
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Table 9-1: Home Block Contents 

Field Location Contents 



a 


000-201 


b 


204-251 


c: 


700-701 


d 


702-703 


e 


722-723 


f 


724-725 


S 


726-727 


h 


730-743 



Bad block replacement table 

INITIALIZE/RESTORE data area 

Reserved for 13IGITAL 

Reserved for DIGITAL 

Pack cluster size 

Block number of first directory segment 

System version 

Volume Identification 



i 744-757 Owner name 

j 760-773 System Identification 

k 776-777 Checksum 



Default 



000000 

000000 

000001 

000006 

Radix-50 V3A 

RTllA and seven 
spaces 

12 spaces 

DECRTUA and four 
spaces 



segments for all RT-11 devices. See the RT-11 Installation and System 
Generation Guide for a patch that changes the default number of 
segments.) In general, you should select many segments if you need to store 
many small files on a large device. By selecting the minimal number of 
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segments and reducing the size of the directory area, you obtain more space 
to store large files on a smaller device. 

Each directory segment consists of a five-word header plus a number of en- 
tries containing file information. Each segment ends with an end-of- 
segment marker. Figure 9-3 shows the general format of the device 
directory. 

Figure 9-3: Device Directory Format 



FIVE-WORD HEADER 



ENTRIES 



END-OF-SEGMENT 
MARKER 



9.1.2.1 Directory Header Format — Each directory segment contains a five- 
word header, which leaves the remaining 507 words of the two-block seg- 
ment for directory entries. Table 9-2 describes the contents of the header 
words. 



Table 9-2: Directory Header Words 

Word Contents 



The total number of segments in this directory. The vaUd range is from 1 
through 31 decimal. If you do not specify the number of segments you 
require when you initialize the device, DUP uses the default number of 
segments for that device. 

The segment number of the next logical directory segment. The direc- 
tory is a linked list of segments and this word is the link between the cur- 
rent segment and the next logical segment. If this word is 0, there are no 
more segments in the list. 

The number of the highest segment currently in use. RT-11 increments 
this counter each time it opens a new segment. Note that the system 
maintains this counter only in word 3 of the header for the first directory 
segment. It completely ignores the third word of the header of the other 
segments. 

The number of extra bytes per directory entry, always an unsigned, even 
octal number. See Section 9.1.2.2 for more information. 

The block number on the device where the actual stored data monitored 
by this segment begins. 
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9.1.2.2 Directory Entry Format — The remainder of the directory segment 
consists of a number of directory entries followed by an end-of-segment 
marker. Figure 9-4 shows the format of a directory entry, 

Figui'e 9-4: Directory Entry Format 



STATUS WORD 



FILENAME (CHARS 1-3) 
IN RAOIX-50 



FILEMAME (CHARS 4-6) 
IN RADIX-50 



FILE TYPE 

(1 TO 3 CHARACTERS) 

IN RADIX-50 



TOTAL FILE LENGTH 



JOB# 



CHANNEL* 



CREATION DATE 



OPTIONAL EXTRA WORDS 



The i'irst word of each directory entry is the status word, which describes 
the condition of the actual files stored on the device. The high-order byte of 
the status word contains a codts representing the type of file. The low-order 
byte is reserved and should always be 0. Figure 9-5 illustrates the status 
word, 

Figure 9-5: Status Word Formiat 



TYPE OF FILE 



RESERVED 



RT-11 uses three kinds of directory entries: 

• tentative entries 

• <5mpty entries 

• permanent entries 
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You can think of the three types of entry as describing areas that are 
categorized as temporary data, available space on the device, or permanent 
data. The device directory contains at all times sufficient entries to describe 
the entire device. 

A tentative file is a file that is in the process of being created. When a pro- 
gram issues the .ENTER programmed request, for example, it creates a 
tentative file. The program must issue a .CLOSE programmed request to 
make the tentative file permanent. If you do not eventually close a ten- 
tative file, the system deletes it. The DIR utility program Usts tentative 
files that appear in directories as < UNUSED > files. 

An empty entry defines an area of the device that is available for use. Thus, 
when you delete a file, you obtain an empty area. DIR lists an empty area as 
<UNUSED>, followed by its length. 

A permanent file is a tentative file that has been closed with the .CLOSE 
programmed request. Permanent files are unique — that is, only one file can 
exist with a specific name and file type on a device. If another file exists 
with the same name and type when the program closes the current ten- 
tative file, the monitor deletes the first file as part of the .CLOSE routine, 
thus replacing the old file with the new file. DIR lists permanent files that 
appear in directories by their file names, file types, sizes, and creation dates. 

Table 9-3 Usts the five valid status word values and their meanings. 
Table 9-3: Status Word Values 

Status Word Meaning 

400 Tentative file. 

1000 Empty area. RT-11 does not use the name, file type, or date fields in the 

directory entry for an empty area. 

2000 Permanent file. 

102000 Protected permanent file (see Section 9.1.2.3). 

4000 End-of-segment marker. RT-11 uses this marker to determine when it 

has reached the end of the directory segment during a directory search. 
Note that an end-of-segment marker can appear as the last word of a 
segment. It does not have to be followed by a name, file type, or other en- 
try information. 

The second, third, and fourth words in a directory entry contain the 
Radix-50 representation of the file name and file type. For empty areas, 
RT-11 normally ignores these words. However, the DIR /Q option (or the 
monitor DIRECTORY command with the /DELETED option) Usts the 
names and file t5T)es of deleted files. 

The fifth word in a directory entry contains the total file length, which con- 
sists of the number of blocks the fUe occupies on the device. Attempts to 
read or write outside the Umits of the file result in an end-of-file error. 
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The sixth word in a directorj^ entry contains the channel number and 
sometimes the job number as well. RT-11 uses this information only for 
tentative files. A tentative file is associated with a job in one of two ways, 
depending on which RT-11 mcmitor is running. 

In the SJ environment, the low byte of the sixth word of the entry holds the 
channel number on which the file is open. This number enables the monitor 
to locate the correct tentative file for the channel when a program issues the 
.CLOSE programmed request. 

In the FB and XM environments, as with SJ, the low byte of the sixth word 
of the directory entry contains the channel number. In addition, the high 
byte of the sixth word contains the number of the job that is opening the 
file. The job number is required to identify the correct tentative file during 
the .CLOSE operation. It is also necessary because several jobs can have 
files open using the same channel number. 

NOTE 

RT-11 uses the sixth word (job number and channel 
number word) only when the file is tentative. Once the file 
becomes permanent, RT-11 no longer uses the word. The 
function of the sixth word while the file is permanent is 
reserved for future use by DIGITAL. 

The seventh word of a directory entry contains the file's creation date. 
When a program creates a tentative file by issuing the .ENTER pro- 
grammed request, the system moves the system date word into the creation 
date slot for the entry. The dat;e word is if you did not enter a date with 
the DATE monitor command. Figure 9-6 shows the format of the date 
word. Bit 15 is reserved for future use by DIGITAL. 

Figuire 9-6: Date Word Format 



15 


14 13 12 11 10 


9 8 7 6 5 


4 3 2 10 




MONTH, 
IN DECIMAL 
(1-12) 


DAY, 
IN DECIMAL 
(1-31) 


YEAR MINUS 110, 
IN OCTAL 



Normally, directory entries are; seven words long, but by using DUP with 
the /Z:n option, you can allocate extra words for each entry when you in- 
itialize the device. The fourth word of the directory header contains the 
number of extra bytes you specify. Although DUP lets you allocate extra 
words, RT-11 provides no means to manipulate this extra information con- 
veniently. Any program that needs to access these words must perform its 
own operations on the RT-]L1 directory. In addition, programs that 
manipulate the directory should use bit test (BIT) instructions, rather than 
compare (CMP) instructions. 
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9.1.2.3 File Protection — RT-1 1 provides a mechanism to prevent a file from 
being deleted. A file is protected when the high bit of its status word is set. 
Note that only permanent files can be protected. You can protect and un- 
protect files by using the PIP /R option or the monitor RENAME com- 
mand. For more information, see the RT-11 System User^s Guide. 

9.1.2.4 Sample Directory Segment — The directory listings shown in Figure 
9-7 describe a single-density diskette with 11 files. 

Figure 9-7: Directory Listings 

DIRECTORY/FULL DXOt 



29-flPR-79 














SMAP .SYS 


24 


19-FEB-79 


RTllSJ 


.SYS 


65 


19-FEB-79 


< UNUSED > 


7? 




PIP 


.SAM 


16 


19-FEB-79 


DUP .SAV 


21 


19-FEB-79 


DIR 


.SAM 


17 


19-FEB-79 


EDIT ,SAV 


19 


19-FEB-79 


LINK 


.SAV 


37 


19-FEB-79 


LIBR .SAV 


20 


19-FEB-79 


DUMP 


.SAV 


7 


19-FEB-79 


MACRO .SAM 


45 


19-FEB-79 


SIPP 


.SAM 


13 


29-APR-79 


< UNUSED > 


119 












11 FILESf 234 


BLOCKS 












196 FREE BLOCKS 












DIRECTORY/SUMMARY DXO: 












29-APR-79 














11 FILES IN 


SEGMENT 


1 










4 AMAILABLE SEGMENTS, 1 IN USE 











11 FILESf 284 FREE BLOCKS 
196 FREE BLOCKS 



Figure 9-8 shows the contents of segment 1 of the diskette directory, ob- 
tained by dumping absolute block number 6 of the device. 

To find the starting block of a particular file, first find the directory seg- 
ment containing the entry for that file. Then take the starting block number 
in the fifth word of that directory segment and add to it the length of each 
permanent, tentative, and empty entry in the directory before your file. For 
example, in Figure 9-8 the permanent file RTllSJ.SYS begins at block 
number 46 octal on the device. 

9.1.3 File Storage on Random-Access Devices 

RT-11 uses the three types of directory entry mentioned previously to com- 
pletely describe the contents of a random-access device. All files reside on 
blocks that are contiguous on a device. There are several advantages and 
disadvantages to this method of storing data. 

When data is stored in contiguous blocks, I/O is more efficient. Transfers to 
large buffers are handled directly by the hardware for certain disks; seeks 
between blocks and program interrupts between blocks are eliminated. File 
data is processed simply and efficiently since the data is not encumbered by 
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Figure 9-8: RT-11 Directory Segment 



HEADER: 


4 

1 

16 


ENTRIES: 


2000 

75131 

62000 

75273 

30 

5147 




2000 

71677 

142302 

75273 

101 

5147 




1000 

16315 

54162 

75273 

115 

5147 




2000 

62570 



73376 

20 

5147 




2000 

16130 



73376 

25 

5147 




2000 

15172 



73376 

21 

5147 




2000 

17751 

76400 

73376 

23 

5147 



FOUR SEGMENTS AVAILABLE 

NO NEiXT SEGMENT 

HIGHEST OPEN IS #1 

NO EXTRA BYTES PER ENTRY 

FILES START AT DEVICE BLOCK 16 OCTAL 

PERMANENT FILE 

RADIX-50FORSWA 

RADIX-50FOR P 

RADIX-50FORSYS 

FILE IIS 30 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED ON 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR RT1 

RADIX-50FOR 1SJ 

RADIX-50 FOR SYS 

101 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED ON 19-FEB-79 

EMPTY AREA (THE FILE DXMNFB WAS DELETED) 

RADIX-50 FOR DXM 

RADIX-50 FOR NFB 

RADIX-50 FOR SYS 

1 1 5 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 
RADIX-50 FOR PIP 
RADIX-50 FOR SPACES 
RADIX-50 FOR SAV 

20 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 
CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR DUP 

RADIX-50 FOR SPACES 

RADIX-50 FOR SAV 

25 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 
RADIX-50 FOR DIR 
RADIX-50 FOR SPACES 
RADIX-50 FOR SAV 

21 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 
CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR EDI 

RADIX-50 FORT 

RADIX-50 FOR SAV 

23 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 
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Figure 9-8: RT-11 Directory Segment (Cont.) 



2000 

46166 

42300 

73376 

45 

5147 



2000 

46152 

70200 

73376 

24 

5147 



2000 

16125 

62000 

73376 

7 

5147 



2000 

50553 

71330 

73376 

55 

5147 



2000 

74070 

62000 

73376 

15 

11647 



1000 

000325 

063471 

023364 

167 



4000 



PERMANENT FILE 

RADIX-50FOR LIN 

RADIX-50FOR K 

RADIX-50FORSAV 

45 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50FOR LIB 

RADIX-50FOR R 

RADIX-50 FOR SAV 

24 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR DUM 

RADIX-50 FOR P 

RADIX-50 FOR SAV 

7 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR MAC 

RADIX-50 FOR RD 

RADIX-50 FOR SAV 

55 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 19-FEB-79 

PERMANENT FILE 

RADIX-50 FOR SIP 

RADIX-50 FOR P 

RADIX-50 FOR SAV 

15 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

CREATED 29-APR-79 

EMPTY AREA (NEVER USED SINCE INITIALIZATION) 

RADIX-50 FOR EM (STORED AT INITIALIZATION) 

RADIX-50 FOR PTY (STORED AT INITIALIZATION) 

RADIX-50 FOR FIL (STORED AT INITIALIZATION) 

167 OCTAL BLOCKS LONG 

USED ONLY FOR TENTATIVE FILES 

(THE DATE IS NOT SIGNIFICANT) 

END-OF-SEGMENT-MARKER 



link words in each block. Routines to maintain the directory are relatively 
small because the directory structure is simple. File operations, such as 
open, delete, and close, are performed quickly with few disk accesses, 
because only the directory must be accessed, and not additional bitmaps or 
retrieval pointers. 
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One disadvantage of this method of storing data is that a small device can 
become fragmented, requiring a squeeze operation to consolidate its free 
space. Another is that once a file is closed, a running program cannot easily 
increase its size. Only a small number of output files can be opened 
simultaneously, even on a large device, unless the limits of the file sizes are 
known in advance. Finally, this scheme precludes the use of multiple and 
hierarchical directories. 

In summary, any method of storing data has its advantages and its disad- 
vantages. The contiguous block; method is used in RT-11 because its simple 
structure and low overhead best suit typical RT-11 applications. 

Figure 9-9 shows a simplified diagram of a random-access device that has a 
total of 250 blocks of space available for files after blocks through 5 and 
the directory are accounted for. The device in the figure has two permanent 
files and one empty area stored on it. 

Figure 9-9: Random-Access Dovice with Two Permanent Files 



PERMANENT 
80 BLOCKS 


EMPTY 

150 BLOCKS 


PERMANENT 
20 BLOCKS 



When you create a file, your program must allocate the space for the file in 
the .ENTER programmed request. If you do not know the actual size, as is 
often the case, the space you allocate should be large enough to accomodate 
aU the data possible. Two special cases for the .ENTER programmed re- 
quest permit you to do this easily. In the first case, a length argument of 
allocates for the file either one-lialf the largest space available, or the second 
largest space, whichever is bigger; in the second case, a length argument of 
- 1 jillocates the largest space possible on the device. 

The monitor creates a tentative file on the device with the length you 
specified. The tentative file must always be followed by an empty area to 
enable the system to recover unused space if less data is written to the file 
than you originally estimated. Figure 9-10 shows an example of a tentative 
file Mirhose allocated size is 100 blocks. Note that the total amount of space 
on the device, 250 blocks in this case, remains constant. 

Figure 9-10: Random-Access Device with One Tentative File 



PERMANENT 
80 BLOCKS 


TENTATIVE 
100 BLOCKS 


EMPTY 
50 BLOCKS 


PERMANENT 
20 BLOCKS 



Suppose, for example, that while the file is being created by one program, 
another program enters a new file, allocating 25 blocks for it. The device 
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would appear as shown in Figure 9-11. Remember that every tentative file 
must be followed by an empty area. 

Figure 9-11: Random-Access Device with Two Tentative Files 



PERMANENT 
80 BLOCKS 


TENTATIVE 
100 BLOCKS 


EMPTY 
BLOCKS 


TENTATIVE 
25 BLOCKS 


EMPTY 
25 BLOCKS 


PERMANENT 
20 BLOCKS 



When a program finishes writing data to the device, it closes the tentative 
file with the .CLOSE programmed request. RT-11 then makes the tentative 
file permanent. The length of the file is the actual size of the data that was 
written. The size of the empty area is its original size plus any unused space 
from the tentative file. 

Figure 9-12 shows the same device after both tentative files are closed. The 
first file's actual length is 75 blocks, and the second file's length is 10 
blocks. 

Figure 9-12: Random-Access Device with Four Permanent Files 



PERMANENT 
80 BLOCKS 


PERMANENT 
75 BLOCKS 


EMPTY 
25 BLOCKS 


PERMANENT 
10 BLOCKS 


EMPTY 
40 BLOCKS 


PERMANENT 
20 BLOCKS 



Because of this method of storing files, it is impossible in RT-11 to extend 
the size of an existing file from within a running program. To make an ex- 
isting file appear to be bigger, you can read the existing file; allocate a new, 
larger tentative file; and write both the old and the new data to the new file. 
You can then delete the old file. 

The DUP utility program provides the /T option as an easy way to extend 
the size of an existing file. However, to use this option, you must have an 
empty file with sufficient space in it immediately following the data file. 
(You can also access this option through the monitor CREATE/EXTEN- 
SION command.) 



9.1.4 Size and Number of Files 

The number of files you can store on an RT-11 device depends on the 
number of segments in the device's directory and the number of extra 
words per entry. If you use no extra words, each segment can contain 72 
entries. 

The maximum number of directory segments on any RT-11 device is 31 
decimal. Use the following formula to calculate the theoretical maximum 
number of directory entries, and thus, the maximum number of files. 



31* 



512-5 

7 -t- N 



- 2 
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N represents the number of ext:ra information words per directory entry. If 
N is 0, the maximum number of files you can store on the device is 2230 
deciraal. 

Note that all divisions are integer and the remainder should be discarded. 

In the formula shown above, the - 2 is required for two reasons. First, in 
order to create a file, the tentative file must be followed by an empty area. 
Second, an end-of-segment entry must exist. Note that on a disk squeezed 
by DUP, the end-of-segment entry might not be a full entry, but may con- 
tain just the status word. 

If you store files sequentiallj'^ (that is, one immediately after another) 
without deleting any files, roughly one-half the theoretical maximum 
number of files will fit on the device before a directory overflow occurs. This 
situation results from the way RT-11 handles filled directory segments. 

When a directory segment becomes full and it is necessary to open a new 
segmient, the monitor moves approximately one-half of the directory entries 
of the filled segment to the new segment. Thus, when the final segment is 
full, all previous segments have approximately one-half of their total capaci- 
ty. See Section 9.1.5 for a detailed explanation of how RT-11 splits a direc- 
tory segment. 

If you add files continually t<j a device without issuing the SQUEEZE 
monitor command, you can use the following formula to compute the max- 
imum number of entries, and thus, the maximum number of files. 

(M-l)*-§ + S 
2 

M rejpresents the maximum number of segments. 
S can be computed from the following formula: 

S= ^^^ -2 

7 -I- N 

N represents the number of ex tra information words per entry. 

You can realize the theoretical total of directory entries (see the first for- 
mula, above) by compressing the device (using the DUP IS option or the 
monitor SQUEEZE command) when the directory fills up. DUP packs the 
directory segments as well as the physical device. 

9.1.5 Splitting a Directory Segment 

Whenever RT-11 stores a new file on a volume, it searches through the 
directory for an empty area that is large enough to accomodate the new ten- 
tative file. When it finds a suitable empty area, it creates the new file as a 
tentative file followed by an empty area, sliding the rest of the directory en- 
tries down to make room for the new entry. Figure 9-13 shows how RT-11 
stores a new file as a tentative file followed by an empty Eirea. 
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Figure 9-13: Storing a New File 

BEFORE 



AFTER 



BLOCK 6 
SEGMENT 1 


HEADER 


PERMANENT 1 


PERMANENT 2 


PERMANENT 3 


EMPTY 


PERMANENT 4 


END-OF-SEGMENT 



BLOCK 6 
SEGMENT 1 



HEADER 


PERMANENT 1 


PERMANENT 2 


PERMANENT 3 


TENTATIVE 


EMPTY 


PERMANENT 4 


END-OF-SEGMENT 



END OF BLOCK? 



END OF BLOCK? 



This procedure works properly as long as the empty entry and the entries 
following it can move downward. However, if the segment is full, the 
monitor must split the segment, if possible, in order to store the new entry. 
Figure 9-14 illustrates a directory segment that is full. 

First, the monitor checks the header for the number of segments available. 
If there are none, a directory full error results and the monitor cannot store 
the new file. You can squeeze the volume at this point to pack the directory 
segments, and try the operation again. 

If there is another directory segment available, the monitor divides the cur- 
rent segment by first finding a permanent or tentative entry near the mid- 
dle of the segment and saving its first word. In place of the first word, the 
monitor puts an end-of-segment marker. It then saves the current link infor- 
mation, links the current segment to the next available segment, and writes 
the current segment back to the volume. 

Next, the monitor restores the first word of the middle entry to the copy of 
the segment that is still in memory, and restores the link information. It 
slides the middle entry and all the entries following it to the top of the seg- 
ment. Then the monitor writes this segment to the volume as the next 
available segment. Finally, the monitor reads segment 1 into memory and 
updates the information in its header, at which point control passes to the 
top of the .ENTER routine, and the monitor begins its search again for a 
suitable empty entry to accomodate the new file. 
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Figure 9-14: Full Directory Segment 



BLOCKS 
SEGMENT 1 



HEADER 


PERMANENT 1 


PERMANENT 2 


PERMANENT 3 


PERMANENT 4 


PERMANENT 5 


. MORE ENTRIES 

• • 

• • 


END-OF-SEGMENT, 
END OF BLOCK? 



Figures 9-15 and 9-16 summariize the process of splitting a directory seg- 
ment. In this example, segment 1 was the only segment in use. It contained 
an empty entry but did not have room for a tentative entry in addition to 
the empty one. After the split, segments 1 and 2 are both about half full. 

After a directory segment spUts,, the monitor can store the new file in either 
the new segment or the old one, depending on which segment now contains 
the empty area. In Figure 9-16, the empty area is in segment 2. 

Thus far, the hnk words seem superfluous since the segments are always in 
numerical order. However, consider a situation in which four segments are 
available: segment 1 fills and overflows into segment 2; segment 2 fills and 
overflows into segment 3; segments 1, 2, and 3 are half full, and they are 
linked in the order in which they are located on the volume (blocks 6, 10, and 
12), The picture changes if you delete a large file from segment 2, leaving a 
large empty entry, and add a lot of small files to the volume. Segment 2 now 
fills up and overflows into the next free segment, segment 4, so that the 
Unks become visibly significant: segment 1 links to 2, segment 2 links to 4, 
and segment 4 links to 3 because segment 2 previously linked to 3. Figure 
9-17 illustrates this example. 

9.1.6 How to Recover Data When the Directory Is Corrupted 

One of the most frustrating experiences you can have as a programmer is to 
lose data on a volume because a block in the device directory went bad or 
because another user wrote over the directory. Usually, in a situation like 
this the files on the volume are intact, but the directory entries for some of 
the files have been destroyed. This section presents some guidelines you 
can follow to recover as much data as possible from a volume with a cor- 
rupted directory. 
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Figure 9-15: Directory Before Splitting 

HIGHEST SEGMENT IN USE: 1 
NUMBER OF SEGMENTS AVAILABLE: 2 



BLOCK 6 
SEGMENT 1 



HEADER 


PERMANENT 1 


PERMANENT 2 


PERMANENT 3 


PERMANENT 4 


PERMANENT 5 


EMPTY 


PERMANENT 6 


PERMANENT? 


END-OF-SEGMENT, 
END OF BLOCK? 



BLOCK 10 
SEGMENT 2 



END OF BLOCK 11 



Figure 9-16: Directory After SpUtting 

HIGHEST SEGMENT IN USE: 2 
NUMBER OF SEGMENTS AVAILABLE: 2 



BLOCK 6 
SEGMENT 1 



HEADER 


PERMANENT 1 


PERMANENT 2 


PERMANENT 3 


PERMANENT 4 


END-OF-SEGMENT 



END OF BLOCK 7 



LINK 



BLOCK 10 
SEGMENT 10 



HEADER 


PERMANENT 5 


EMPTY 


PERMANENT 6 


PERMANENT ? 


END-OF-SEGMENT 



END OF BLOCK 11 
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Figure 9-17: Directory Links 



HIGHEST SEGMENT IN USE: 3 
NUMBER OF SEGMENTS AVAILABLE: 4 



BLOCK 6 

SEGMENT 1 



LINK 



BLOCK 10 
SEGMENTS 


LINK 







BLOCK 12 
SEGMENTS 



HIGHEST SEGMENT IN USE: 4 
NUMBER OF SEGMENTS AVAILABLE: 4 



BLOCK 6 
SEGMENT 1 


LINK 


BLOCK 10 

segment:! 


LINK 


BLOCK 12 

SEGMENTS 


LINK 


BLOCK 14 
SEGMEI*T4 






















t 



9.1.6/1 Examine Segment 1 — Your first step in recovering data is to deter- 
mine whether or not segment 1 of the directory is bad. Remember, segment 
1 occupies physical blocks 6 and 7 of the device. To examine segment 1, 
mount the volume and try to get an ordinary listing of the files. Use the 
DIRlilCTORY monitor command without any options. 

If you get an immediate ?MON-F-Directory I/O error or ?MON-F-Dir I/O err 
message, you know that segment 1 is bad. This leaves you with two alter- 
natives: you can reformat and reinitialize the volume (the volume is 
reusable if a bad block scan shows no bad block in the directory area); or, if 
you are desperate to recover the data on the volume, you can open the 
volume in non-file-structured mode with TECO and search for data that 
resembles source code or other ASCII information that looks familiar. This 
kind of search is a tedious process; you probably shouldn't even consider it 
unless you have a video terminal to use with TECO. See Section 9.1.6.4 for 
information on removing a file from the volume. 

If, on the other hand, the DIIIECTORY monitor command gives you at 
least a partial directory listing, you will be able to recover some of the infor- 
mation from the volume by issuing the DIRECTORY/SUMMARY monitor 
command. The /SUMMARY option lists information up to but not in- 
cluding the bad segment. To recover as many files as possible, you must 
repair the directory by linking around the bad segment. 

9.1 .6.2 Follow the Chain of Segments — Use SIPP to open the volume in non- 
file-structured mode. Look firsi: at location 6000, which is the start of the 
header for directory segment 1. It contains the total number of segments 
available. Location 6002 contains the number of the next segment, and loca- 
tion 6i004 shows the highest segment in use. (To review the directory header 
words and their meanings, see Table 9-2.) 

To find the absolute location of the next segment, multiply the link word by 
2000 and add 4000. For example, if the link word is 2, the next segment 
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starts at location 10000 on the volume. Chain your way through the 
segments by opening the next segment and following its link word. As you 
go, make a worksheet for the link information, according to the format 
shown in Figure 9-18. Continue chaining until you have accounted for all 
the segments. Remember that segment 1 is always the first segment — that 
is, nothing links to it. The last segment always links to 0. 

Figure 9-18: Worksheet for a Directory Chain with Four Segments 



HIGHEST SEGMENT IN USE: f- 
NUMBER OF SEGMENTS AVAILABLE: f- 



SEGMENT: 
1 


LINKED TO: 
2 


2 


4 


+ 


3(bad 


3(&ad; 


? 



In Figure 9-18, segment 3 must link to — that is, it is the last segment 
since all the others have been accounted for already. To repair this direc- 
tory, modify the header of segment 4 so that the Unk word contains in- 
stead of 3. This eliminates segment 3 from the chain. Section 9.1.6.3 
describes how to remove the files from the volume. 

Figure 9-19 shows a more complicated example. In this case the bad seg- 
ment is not the last one in the directory. 

In a situation of the kind shown in Figure 9-19, you can follow the chain 
from segment 1 through segment 8, which points to the bad segment. To 
continue from that point, enter in the left column the lowest segment 
number not yet accounted for and follow its link. Remember, if a segment 
Unks to 0, it is the last segment in the directory. Continue until all the 
segments are accounted for in the left column. When you finish, the number 
that is missing from the right column is the segment to which the bad seg- 
ment links. In Figure 9-19, this is segment 6. As in the previous example, 
use SIPP to link around the bad segment. In this case, change the Hnk word 
in segment 8 to point to segment 6, thus removing segment 7 from the 
chain. 

9.1.6.3 Remove the Data from the Good Segments — Once you have eliminated 
the bad segment by linking around it, you are ready to save the files whose 
entries appear in the good segments. Use the monitor COPY command to 
copy the files to a good volume. The following command, for example, 
copies all the files from one diskette to another: 

COPY DXO:*.* DX1:<RET> 
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This procedure removes all the files from the volume except those whose en- 
tries appear in the bad segment. 

Figuire 9-19: Worksheet for a Directory Chain with Nine Segments 

HIGHEST SEGMENT IN USE: 9 
NUMBER OF SEGMENTS AVAILABLE: ? 



SEGMENT: 
1 


LINKED TO: 

2 


2 


5 


S 


4 


4 


5 


8 


7Cbad 


7cbad;) 


? 


3 





6 


9 


9 


3 



9.1.6.4 Remove the Data from the Bad Segment — You can sometimes save 
files whose entries appear in the bad segment by using SIPP and DUP. If, 
when you open the segment with SIPP, block 1 of the segment is 
unreadable, you should probably give up because chances are that even if 
block 2 of the segment is readable, it contains old data that is not vahd. 

If you can read block 1, decodts the header and the entries according to the 
diagram in Figure 9-4. Continuing with SIPP, try to locate the files on the 
volume. (Section 9.1.2.4 explains how to locate a file on the volume.) Once 
you establish the starting and ending blocks of a specific file, run DUP and 
use the following command se(5uence to transfer the file to a new device: 

output-filespec = lnput-devlce:/G:startblock/E:endblock/l/F 

You can use the following keyboard monitor command to achieve the same 
results: 

COPY/DEVICE/FILeSTART:startblock/END:endblock Input-device output-filespec 

When you have finished removing files from the volume, you can return it 
to another user (if someone wrote over the directory); or, you can reformat 
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and initialize it (if there was a bad block in the directory area). If reformat- 
ting does not remove the bad block, label the volume clearly so you don't ac- 
cidentally use it again. 

9.1.7 Interchange Diskette Format 

You can use the FILEX /U option (or the monitor COPY/INTERCHANGE 
command) to transfer data between RT-11 devices and interchange 
diskettes. An interchange diskette, also known as an IBM floppy disk, con- 
sists of 77 tracks. Each track contains 26 decimal sectors, and you can store 
one record of 128 or fewer characters per sector, using EBCDIC format. 

Track of the diskette is reserved for dataset labels, which are a form of 
directory. The functions of the sectors of track are as follows. 

Sectors 1 through 4 are reserved by IBM for system use. There are 80 
blanks per sector. 

Positions 1 through 13 of sector 5 are used to record the identity of an error 
track. Positions 1 through 5 contain ERMAP to identify the sector as an er- 
ror map. Sector 5 is not supported by RT-11. 

Sector 6 is reserved by IBM for system use. It contains 80 blanks. 

Sector 7 is the volume label. Positions 1 through 4 (bytes through 3) con- 
tain VOLl in EBCDIC. This identifies the diskette as an IBM floppy. 
Within DIGITAL, these four bytes identify the system that wrote the 
diskette. RT-11 stores RTll here. Other fields in sector 7 identify the 
diskette, its format, and its owner, and indicate whether or not the diskette 
uses standard labels. Table 9-4 describes the contents of sector 7. 

Table 9-4: Interchange Diskette Sector 7 

Offset Byte Contents 

V 
O 
L 

1 

Bytes 5 through 10 contain the volume ID field. The ID con- 
sists of one to six digits or letters (left-justified); unused posi- 
tions must contain blanks. 

Access code. Must be blank to permit access to diskette. 
Bytes 12 through 37 are reserved by IBM. 
Bytes 38 through 51 contain the owner ID field. Not all 
systems use this field. 
Bytes 52 through 76 are reserved by IBM. 
Bjftes 77 and 78 are the record sequence field, or interleave 
factor. 

Two blanks represents 1:1 interleave. 
Reserved by IBM. 
117 80 Label version field. W indicates standard labels. 
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1 


2 


2 


3 


3 
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4 


5 


12 


11 


13 


12 


45 


38 


63 


52 


114 


77 


115 


78 


116 


79 
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Sectors 8 through 26 are the dataset labels. They are 40 words long, and 
contain directory information. Table 9-5 describes the contents of sectors 8 
throuigh 26. 



Table 9-5: Interchange Diskette Sectors 8 Through 26 

OfiFset Byte Contents 



H 
D 
R 

1 

Reserved. 

Bytes 6 through 13 contain the user name for the dataset 
(the file label). 

Bytes 14 through 22 are reserved. 

Bytes 23 through 27 contain the block/record length. The 
default is 80, but 128 is possible. 
Reserved. 

Bytes 29 and 30 contain two EBCDIC characters represent- 
ing the track number of the beginning of data. 
EBCDIC (octal 360). 

Bytes 32 and 33 contain two EBCDIC characters represent- 
ing the sector number of the beginning of data. 
Reserved. 

Bytes 35 and 36 contain two EBCDIC characters represent- 
ing the number of the last track reserved for this dataset. 
EBCDIC (octal 360). 

Bytes 38 and 39 contain two EBCDIC characters represent- 
ing the number of the last sector reserved for this dataset. 
Reserved. 
Bj^ass indicator. 
Dataset security. 
Write pirotect. 

Blank for data interchange (octal 100). 
Multi-volume indicator: C = Continued, L = Last, 
blank = Not continued. 

Bytes 46 and 47 contain the volume sequence number. 
Bytes 48 and 49 contain the creation year (such as 80). 
Bytes 50 and 51 contain the creation month. 
Bytes 52 and 53 contain the creation day. 
Bytes 54 through 66 are reserved. 

Bytes 67 through 72 contain the expiration date (in the same 
format as the creation date). 

Verify mark: V = Dataset verified, blank = Not verified. 
Reserved. 

Bytes 715 through 79 contain the number of the next unused 
track and siector within this dataset. 
Bytes 75 and 76 contain the track number. 
EBCDIC 0. 

Bytes 78 and 79 contain the number of the next unused 
sector. 
Reserved. 
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41 
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48 


61 
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65 
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110 


73 
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9.2 Sequential-Access Devices 

The two RT-11 devices that are file-structured but not random-access are 
magtape and cassette. This section describes the formats of those two 
sequential-access devices and shows how RT-11 stores files on them. 

9.2.1 Magtape Structure 

With RT-11 V04 you can read magtapes created with versions V2C, V03, 
and V03B. RT-11 automatically writes magtapes using a subset of the 
VOLl, HDRl, and EOFl labels (ANSI standard X3.27 level 1). 

RT-11 magtape implementation includes the following restrictions: 

1. There is no EOV (end-of- volume) support. This means that no file can 
continue from the end of one tape volume to another volume. 

2. RT-11 does not ignore noise blocks on input. 

3. RT-11 assumes that data is written in records of 512 characters per 
block. The logical record size equals the physical record size. 

NOTE 

The hardware magtape handler (as opposed to the file 
structure magtape handler) can read data in any format at 
all. You can also make use of .SPFUN programmed re- 
quests and the file structure magtape handler to read tapes 
with data in a nonstandard format (see Chapter 10 for 
details). The RT-11 utility programs, such as PIP, DUP, 
and DIR, can only read and write tapes in the standard 
RT-11 format of 512-character blocks. 

4. RT-11 does not check access fields and therefore provides no volume 
protection. 

In the following examples, an asterisk (*) represents a tape mark. The struc- 
ture of the actual tape mark itself depends on the encoding scheme that the 
hardware uses. A typical nine-channel NRZ tape mark consists of one tape 
character (octal 23) followed by seven blank spaces and an LRCC (octal 23). 
Consult the hardware manual for your own tape device if the format of the 
tape mark is important to you. 

A file stored on magtape has the following format: 

HDR1 * data * E0F1 * 

A volume containing a single file has the following format: 
VOLl HDRl * data * EOFl * * * 

A volume containing two files has the following format: 
VOLl HDR1 * data * E0F1 * HDR1 * data * E0F1 * * * 
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A double tape mark following an EOFl * label indicates logical end of tape. 
(Note that the EOFl label is considered to consist of the actual EOFl infor- 
mation plus a single tape mark.) 

A magtape that has been initialized has the following format: 

V0L1 HDR1 * * EOFl * * * 
A bootable magtape is a multi-file volume that has the following format: 

V0L1 BOOT HDR1 * data * EOF1 * * * 

To create an RT-11 bootable magtape, you must copy the primary 
bootstrap by using the INITIALIZE/FILE :MBOOT command. The 
primary bootstrap is represented by BOOT in the format given for a 
bootable magtape. It occupies a 256-word physical block. The first real file 
on the tape must be the secondary bootstrap, the file MSBOOT.BOT. If the 
tape is designed to allow another user to create another bootable magtape, 
you should copy the file MBOOT.BOT to the tape, as a file. (This is in addi- 
tion t;o copying it into the boot block at the beginning of the tape.) More 
detailed instructions for building bootable magtapes are in the RT-11 In- 
stallation and System Generation Guide. 

Each label on the tape, as shown in the formats of the various magtape 
structures, occupies the first 80 bytes of a 256-word physical block, and 
each byte in the label contains an ASCII character. (That is, if the content 
of a byte is listed as '1', the byte contains the ASCII code and not the octal 
code for '1'.) Table 9-6 shows the contents of the first 80 bytes in the three 
labels. Note that the VOLl, HDRl, and EOFl occupy a full 256-word block 
each, of which only the first 80 bytes are meaningful. 

The meanings of the table headings for Table 9-6 are as follows: 

CP: Character piosition in label 

Field Name: Reference name of field 

L: Length of field in bytes 

Content: Content of field 

(space): ASCII space character 

Table 9-6: ANSI Magtape Labels in RT-11 
CP Field Name L Content 



Volume Header Label <V0L1) 






1-3 


Label identifier 


3 


VOL 


4 


Label number 


1 


1 


5-10 


Volume identifier 


6 


Volume Label. If you do not specify a volume 
ID at initialization time, the default is 
RTllA(space). 


11 


Accessibility 


1 


(Space) 


12-37 


Reserved 


26 


(Spaces) 


38-50 


Owner identifier 


13 


CP38 = D 
CP39 = % 
CP40 = B 

This means tape was written by DEC 

PDP-11. 
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Table 9-6: ANSI Magtape Labels in RT-11 (Cont.) 
CP Field Name L Contents 



51 DEC standard version 

52-79 Reserved 

80 Label standard version 

File Header Label (HDRl) 

1-3 Label identifier 

4 Label number 

5-21 File identifier 



22-27 File set identifier 
28-31 File section number 
32-35 File sequence number 



36-39 Generation number 
40-41 Generation version 
42-47 Creation date 



48-53 Expiration date 



54 
55-60 
61-73 
74-80 



Accessibility 
Block count 
System code 
Reserved 



First End-of-File Label (EOFl) 



CP41-50 = Owner Name. Maximum is 10 char- 
acters; default is (spaces). 

1 1 
28 (Spaces) 

1 3 



3 HDR 

1 1 

17 The six-character ASCII file name, dot, three- 
character file type. (You can use spaces to pad 
the file name to six characters; you can write 
the dot without the padding). This field is left- 
justified and followed by spaces. 
6 RTllA(space) 

4 0001 

4 First file on tape has 0001. This value is in- 
cremented by 1 for each succeeding file. On a 
newly initialized tape, this value is 0000. 

4 0001 

2 00 

6 (Space) followed by (year*1000) + day in 
ASCII; (space) followed by 00000 if no date. For 
example, 2/1/75 is stored as (space)75032. 

6 (Space) followed by 00000 indicates an expired 
file. 

1 (Space) 

6 000000 

13 DECRTllA(space) followed by spaces. 

7 (Spaces) 



This label is the same as the HDRl label, with the following exceptions: 
1-3 Label identifier 3 EOF 



55-60 Block count 



Number of data blocks since the preceding 
HDRl label, unless you issue an .SPFUN pro- 
grammed request. If you issue .SPFUNs, the 
block count is 0. However, if the only special 
function operations you do are 256-word 
.SPFUN writes, the block count is accurate. 



9.2.2 Cassette Structure 

A blank, newly initialized TU60 cassette appears in the format shown in 
Figure 9-20. 

A cassette with a file on it appears as shown in Figure 9-21. The header 
block contains file names. 
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Figure 9-20: Initialized Cassette Format 



CLEAR 
LEADER 


EXTENDED 
FILE GAP 


SENTINEL 

FILE 

32 BYTES 

DECIMAL 


UNPREDICTABLE 
INFORMATION 


Figure 9-21: 


Cassette with D'ata 




CLEAR 
LEADER 


EXTENDED 
FILE GAP 


HEADER 
BLOCK 


BLOCK 
GAP 


DATA 
BLOCK 


BLOCK 
GAP 


DATA 
BLOCK 


FILE 
GAP 


SENTINEL 

FILE 






1 

32 BYTES 
DECIMAL 




1 

128 BYTES 
DECIMAL 











Files normally have data written in 128-byte decimal blocks. You can alter 
this by writing cassettes in hardware mode. In hardware mode, your pro- 
gram must handle the processing of any headers and sentinel files. In soft- 
ware mode, the handler autorciatically does this. 

Figure 9-21 illustrates a file terminated in the usual manner by a sentinel 
file. However, the physical en<i-of-cassette can occur before the actual end 
of the file. This format appears as shown in Figure 9-22. 

Figure 9-22: Physical End-of-Cassette 



(1) 



BLOCK 
GAP 


DAT/s. 
BLOCK 


BLOCK 
GAP 


CLEAR 
TRAILER 



OR: 



(2) 



BLOCK 
GAP 


DATA 
BLOCK 


BLOCK 
GAP 


DATA 
BLOCK 


CLEAR 
TRAILER 



(PARTIALLY 
WRITTEN) 

In case 2, for multi-volume processing the partially written block must be 
rewritten as the first data block of the next volume. 

The file header is a 32-byte decdmal block that is the first block of any data 
file on a cassette. If the first bj'^te of the header is null (000), the header is in- 
terpreted as a sentinel file, which is an indication of logical end-of-cassette. 
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The format of the header is illustrated in Table 9-7. The data in Table 9-7 is 
binary (that is, equals a byte of 0) unless it is specified to be ASCII. 

Table 9-7: Cassette File Header Format 

Byte 
Number Contents 

0-5 File name in ASCII characters (ASCII implies a seven-bit code). The 

first character of a deleted file's name contains either a binary or a 
binary 177. 
6-8 File type in ASCII characters. 

9 Data type (0 for RT-11 ). 

10-11 Block length of 128 decimal, 200 octal (byte 10 = 0, high order; 

byte 11 = 200, low order). 

12 File sequence number (0 for single volume file or the first volume of a 
multi-volume file; successive numbers are used for continuations). 

13 Level 1 (This byte is a 1. You must change this byte to if you are using 
CAPS-11 to load files. See the -RT-ii Installation and System Genera- 
tion Guide for details.). 

14-19 Date of file creation (six ASCII digits representing day (0-31); month 

(0-12); and last two digits of the year; or 40 octal in first byte means no 
date present). 

20-21 

22 Record attributes (0 is RT-11 cassette). 

23 -28 Reserved for DIGITAL. 

29-31 Reserved for your special applications. 
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Chapter 10 

Programming for Specific Devices 



This chapter provides information on device handlers that have special 
device-dependent characteristics. Read this chapter if you need to program 
specifically for one of the following devices: 

1. Magtape handlers: MM, MS, and MT 

2. Cassette handler: CT 

3. Diskette handlers: DX and! DY 

4. Card reader: CR 

5. High-speed paper tape rea<ier and punch: PC 

6. Console terminal handler: TT 

7. Disk handlers: DL and DIVL 

8. Null handler: NL 

9. DECtape II handler: DD 

10.1 Magtape Handlers (MM, MS, MT) 

Magnetic tape is file-structured, but not random-access. This means that it 
stores files sequentially but has no directory at the beginning of each tape. 
RT-11 magtape handlers support a file structure that is compatible with 
ANSI tape labels and format, ^vhich gives you full access to the tape con- 
troller without concern for the specifics of the device. See Chapter 9 for 
more information on the format of magtapes and tape labels. 

NOTE 

Support for RT-11 magtape file structure is compatible 
only among systems that support DEC and ANSI stan- 
dards for tape labels and file formats. DOS-formatted 
tapes cannot be read oi" written. 

RT-11 magtape handlers exist in two versions: a hardware handler and a 
file structure handler. All the handlers are included in the distribution kit. 
Hardware handlers are named MMHD.SYS, MSHD.SYS, and MTHD.SYS. 
File structure handlers are named MM.SYS, MS.SYS, and MT.SYS. 

The handlers for MM and MT accept SET commands to set the number of 
tracks, the density, and the pariity of the tape drive; these commands apply 
to all units of a particular controller. These commands are described in 
Chapter 4 of the RT-11 System User's Guide. The MS handler does not ac- 
cept SET commands. 
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The MM and MT handlers support up to eight tape drives with one con- 
troller. The MS handler supports up to eight drives and eight controllers. 
DIGITAL recommends that you use a file structure handler (unless special 
circumstances indicate that a hardware handler is appropriate), since only 
the file structure handlers can communicate with the RT-11 system utility 
programs. The following sections describe these handlers. 

This chapter uses some magtape-specific abbreviations. They are: BOT, for 
beginning-of-tape; EOT, for physical end-of-tape; LEOT, for logical end-of- 
tape, and EOF, for end-of-file. LEOT consists of an EOFl label (which in- 
cludes one tape mark) followed by two tape marks. 

10.1.1 File Structure Magtape Handler 

The file structure magtape handlers combine the hardware handler, describ- 
ed in Section 10.1.2, with a file structure module. The file structure module, 
which is designed to operate with any magtape handler, permits the handler 
to accept file structure requests. The file structure magtape handler is a 
superset of the hardware handler. You can issue hardware commands to the 
file structure handler. The file structure magtape handlers are named 
MM.SYS, MS.SYS, and MT.SYS. The distributed versions of these 
handlers support tape drives and 1. You can add support for more drives 
at system generation time. 

A tape containing two files has the following format: 

V0L1 HDR1 * data * E0F1 * HDR1 * data * EOFl * * * 

VOLl, HDRl, and EOFl are ANSI tape labels. The asterisk (*) represents a 
tape mark. See Chapter 9 for more information on magtape formats. 

10.1.1.1 Searching by Sequence Number— The file structure handler can 
search for files on tape based on their sequence number. It uses the relation- 
ship between the current tape position and the desired new position to find 
the desired file according to the f oUbwing algorithm: 

1. When the file sequence number for the desired file is greater than the 
number of the current position, the handler moves the tape forward. 
For example, if the tape is currently positioned at file sequence number 
1, and the desired file is number 2, the tape moves forward from its 
position at the tape mark after file number 1 to the tape mark at the 
start of file number 2. 

2. When the file sequence number for the desired file is less than the 
number of the current position, the handler optimizes its seek time by 
moving the tape backward or forward, depending on the location of the 
file. In practice, the handler almost always rewinds the tape and then 
searches forward. 

For example, assume the number of the current position is 2 and the 
desired file has sequence number 1. The tape leaves its position at the 
tape mark for file 2 and rewinds to the beginning of the volume. It then 
moves forward to the tape mark at the start of file 1. As another exam- 
ple, assume the current position is 9 and the desired file has sequence 
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number 6. The tape rewinds to the beginning of the volume and the 
search proceeds in the forward direction. 

If you release the handler through the UNLOAD command or the 
.RELEASE programmed request, the file position is lost. In this situation 
the tape moves backward until the handler locates BOT or a label from 
which it can determine the tape's position. 

10.1.1.2 Searching by File Name — The file structure handler can search for 
files on tape based on their file names. The routine to match file names uses 
an algorithm that enables the handler to recognize file names and file types 
used by other DIGITAL operating systems. The handler uses the file iden- 
tifier field, translating the contents to a recognizable file name. This file 
name is matched to a file name stored in Radix-50 format. The format is as 
follows: 

filnam.typ 

filnam is a valid RT-11 file name left-justified in a six-character field and 
padd(}d with spaces, if necessary. 

typ is a file type left-justified in a three-character field. 

The algorithm the handler uses allows RT-1 1 V03 and later versions to read 
and match tapes written under V2C and earlier versions. RT-11 tapes can 
be detected by the presence oiRTll in character positions 64 through 67 of 
the HDRl label. The algorithm is as follows: 

1. (ylear the character count (CC). 

2. (]!heck the first character in the file name. If it is a dot, do the following: 

a. Mark a dot found. 

b. When CC < 6, insert spiaces and increment the CC until it 
equals 6. 

c. When CC > 6, delete characters and decrement the CC until 
it equals 6. 

3 . If CC = 6 and if RTll is found in character positions 64 through 67 of 
the system code field, insert a dot in the translated name, mark the dot 
found, and increment CC. 

4. Move the character into the translated file name and point to the next 
character. 

5. Increment the CC. 

6. When CC<9 go back to step 2. 

7. Check the dot-found indicator. If no dot was found, back up four 
ciharacters and insert .DAT for the file type. 

8. Perform a character-by-character comparison between the desired file 
name and the file name that was just translated from the file identifier 
field in the HDRl label. When they match exactly, consider the file 
iound. 

Programming for Specific Devices 10-3 



10.1.1.3 Programmed Requests — The following sections describe how pro- 
grammed requests for magtape function. 

.ENTER Programmed Request 

The .ENTER programmed request writes a HDRl label and tape mark on 
the tape, and leaves the tape positioned after the tape mark. The request in- 
itializes some internal tables, including entries for the last block written 
and current block number. (The last block or file on tape is always the most 
recent one written.) The information for the internal tables and entries for 
the last written block is correct unless an .SPFUN request is performed on 
that channel. Normally, files opened with an .ENTER request do not have 
special functions performed on them, except when a nonstandard block size 
is to be written (one that is not 256 words long). To write a nonstandard 
block, open the file with an .ENTER request; then issue an .SPFUN write 
request. Close the file with a .CLOSE request after the operation is com- 
plete. If a file search is to be performed, open the tape non-file-structured 
with a .LOOKUP request. Table 10-1 shows the sequence number values 
for .ENTER requests. 

The .ENTER programmed request has the following format: 

.ENTER area,chan,dblk„seqnum 



Table 10-1: Sequence Number Values for .ENTER Requests 

Seqnum 
Argument File Neune Action Taken Tape Position 



> not null Position at file sequence 

number and perform an 
.ENTER. 



Found: ready to write. 
Not found: at LEOT; 
LEOT is an EOFl label 
followed by two tape 
marks. LEOT is different 
from the physical end-of- 
tape. 



not null Rewind tape and search 

tape for file name. If 
found then give error. If 
not found then enter the 
file. 

1 not null Position tape at LEOT 

and enter file. 

■ 2 not null Rewind tape and search 

tape for file name. Enter 
file at found file or LEOT, 
whichever comes first. 



Found: before file. 

Not found: ready to write. 



Ready to write. 



Ready to write. 



null 



Perform a non-file- 
structured .LOOKUP. 



Tape is rewound. 
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The .ENTER request returns the errors shown in Table 10-2. 
Table 10-2: .ENTER Errors 



Byte 52 
Code Meaning 

Channel in use. 

1 Device full. EOT was detected while writing HDRl. Tape is positioned 
after the first tape mark following the last EOFl label on the tape. 

2 Device already in use. Magtape already has a file open on that unit, 

3 File exists, cannot be deleted. 

4 File sequence numljer not found. Tape is positioned the same as for 
device full. 

5 Illegal argument error. A seqnum argument in the range - 3 through 
- 32767 was detected. A null file name was passed to .ENTER. 



The .ENTER request issues a directory hard error if errors occur while 
entering the file. 

.LOOKUP Programmed Request 

The .LOOKUP request causes a specific HDRl label to be searched and 
read. After this request, the tape is left positioned before the first data 
block of the file. Table 10-3 shows the sequence number values for the 
.LOOKUP request, which has the following format: 

.LOOKUP area,chan,dblk,seqnum 

Table 10-3: Sequence Number Values for .LOOKUP Requests 

Seqnum 
Argmment File Name Action Taken Tape Position 

null Perform a non-file- Rewound. 

stiuctured .LOOKUP. 

-1 null Perform a non-file- Not moved. 

stmctured .LOOKUP. 

> null Perform a file-structured Found: ready to read first 

.LOOKUP on the file se- data block, 
quence number. Not found: at LEOT. 

not null Rewind to the beginning Found: ready to read first 

of tape, then use file name data block, 

to perform a file- Not found: at LEOT. 
stj-uctured .LOOKUP. 

- 1 not null Do not rewind; perform a Found: ready to read first 
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Table 10-3: Sequence Number Values for .LOOKUP Requests (Cont.) 

Seqnum 
Argument File Name Action Taken Tap Position 

file-structured .LOOKUP data block. 

for a file name. Not found: at LEOT. 

> not null Position at file sequence Found: ready to read first 

number and perform a data block, 
file-structured .LOOKUP. Not found: at LEOT. 
If file name does not 
match file name given, 
return error. 

NOTE 

If a channel is opened with a non-file-structured .LOOKUP 
(file name null and file sequence number or - 1), .READ, 
.READC, and .READW requests use an implied word 
count equal to the physical block size on the tape; .WRITE, 
.WRITC, and .WRITW requests use the word count to 
determine the block size on the tape. This convention is 
used instead of using 512 bytes as a default block size and 
performing blocking and unblocking. This request is 
almost identical to an .SPFUN read or write that does not 
report any errors {blk = 0). Also note that the error and 
status block must not be overlaid by the USR. 

The .LOOKUP returns the errors shown in Table 10-4. 

Table 10-4: .LOOKUP Errors 
Byte 52 Code Meaning 

Channel in use. 

1 File not found. Tape is positioned after the first tape mark following the 
last EOFl on the tape. 

2 Device in use. Magtape already has a file open. 

5 Illegal argument error. A seqnum argument in the range — 2 through 

- 32767 was detected. A .LOOKUP request for the hardware handler 
must have a positive sequence number. 

The .LOOKUP request issues the directory hard error in the same manner 
as the .ENTER request. 

.READx Programmed Requests 

NOTE 

The term .RE ADx/.WRITx refers to the following group of 
programmed requests: .READ, .READC, .READW, 
.WRITE, .WRITC, and .WRITW. 
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The .llEADx requests read datfi from magtape in blocks of 512 bytes each. 
This jjroup of requests is described here for files opened with the .ENTER 
and file-structured .LOOKUP requests. In addition to this description, 
there are .READx and .WRITx descriptions appropriate to non-file- 
structured .LOOKUP requests (see Sections 10.1.2.11 and 10.1.2.12). 

If a request is issued for fewer tlian 512 bytes, the handler reads the correct 
number of bytes. If the request is for more than 512 bytes, the handler per- 
forms the request with multiple 512-byte requests (the last request may be 
for fewer than 512 bytes). The .READx requests are valid in a file opened 
with a .LOOKUP request. Thtsy are also valid in a file opened with an 
.ENTER request, provided the block number requested does not exceed the 
last block written (0 code returned). If a tape mark is read, the routine 
repositions the tape so that another request causes the tape mark to be read 
again, When a .CLOSE is issued to a file opened by an .ENTER request, the 
tape is not positioned after the last block written. This causes loss of infor- 
mation when a program issues a read for a block that was written before the 
last block and fails to reread thfs last block, thereby positioning the tape at 
the end of the data. 

The guideUnes for block numbers are as follows: 

1. .READx: When a .LOOKirP is used (to search the file) with this re- 
quest, the handler tries to position the tape at the indicated block 
number. When it cannot, a (EOF code) is issued, and the tape is posi- 
tioned after the last block on the file. 

2. .WRITx and .READx: On an entered file, a check is made to determine 
if the block requested is past the last block in the file. If it is, the tape is 
not moved and the error code is issued. 

The format of the .READx request is as follows: 
.READx area,chan,buf,wcnt,blk[crtn] 

Table 10-5 shows the errors th(; .READx requests return. 
Table 10-5: .READx Errors 
Byte 52 Code Meaning 

Attempt to read past a tape mark; also generated by block that is 
too large. 

1 Hard error occurred on channel. 

2 Channel not open. 



. WRITx Programmed Requests 

The .WRITx requests write data to magtape in blocks of 512 bytes. If a re- 
quest is issued for fewer than 512 bytes, the handler forces the writing of 
512 bytes from the buffer address. If a request is issued for more than 512 
bytes, the handler performs multiple 512-byte transfers. 



Programming for Specific Devices 10-7 



The .WRITx requests are valid in a file opened with an .ENTER or with a 
non-file-structured .LOOKUP. The .WRITx requests have the following 
format: 

.WRITx area,chan,buf,wcnt,blk[,crtn] 

Table 10-6 shows the errors the .WRITx requests return. 



Table 10-6: .WRITx Errors 

Byte 52 Code 



Meaning 



End-of-tape. This means that the data was not written, but the previous 
block is valid. Also issued if the block number is too large. 

1 Hard error occurred on channel. 

2 Channel not open. 



After a write operation the rest of the tape may be undefined (see Figure 
10-1). 

Figure 10-1: Operations Performed After the Last Block Written on 
Magtape 



EXAMPLE 1 
(WRITE) 



BOT 



GAP 




GAP 




GAP 




EXAMPLE 2 
(REWIND/READ) 



BOT 



GAP 



JZ 




GAP 




GAP 




HEAD 

ANY REQUEST FROM 
'this POINT 



EXAMPLES 
(HEAD POSITION 
AFTER READ) 



r^H 



EAD 

i REMAINDER 

OF TAPE 
MAYBE 
UNDEFINED 




HEAD 

SAME AS 
EXAMPLE 1 



In example 1 in Figure 10-1, blocks A, B, and C are written on the tape with 
the head positioned in the gap immediately following block C. Any forward 
operation of the tape drive except by write commands (that is, write, erase 
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gap and write, or write tape mark) yields undefined results due to hardware 
restrictions. 

In example 2 in Figure 10-1, the head is shown positioned at BOT after a re- 
wind operation so that successive read operations can read blocks A, B, and 
C. The head is left positioned us shown in example 3. Note that this is the 
same condition as shown in example 1, and all restrictions indicated in ex- 
ample 1 are appUcable. 

.DELETE and .RENAME Programmed Requests 

The .DELETE and .RENAME requests are invalid operations on magtape, 
and any attempt to execute them results in an illegal operation code (code 2) 
being returned in byte 52. 

.CLOSE Programmed Request 

The .CLOSE request operates in three different ways, depending on how 
the file was opened: 

1. When a file is opened with an .ENTER request, the file is closed by 
writing a tape mark, an EOFl label, and three more tape marks. In this 
operation, the tape is left positioned just before the second tape mark 
at LEOT. Note that the njst of the tape is no longer readable. 

2. When a file is opened with a file-structured .LOOKUP, the tape is posi- 
tioned after the tape mark following the EOFl label for that file. 

3. When a file is opened with a non-file-structured .LOOKUP, no action is 
taken and the channel becomes free. 

The .CLOSE request has the following format: 

CLOSE Chan 

This request issues a directory hard error if a malfunction is detected. The 
error can be recovered with the .SERR request. 

.SPFUN Programmed Request 

The .SPFUN programmed retjuest can perform asynchronous directory 
operations without the USR, which makes it useful for long tape searches. 
It is particularly useful for programmers in multi-job systems who do not 
want to wait for the long tape searches that can occur during .ENTER and 
.LOOKUP requests. It is also useful and desirable for FB and XM users 
who do not want to lock the USR. This request allows the .ENTER and 
.LOOKUP requests to be issued after a non-file-structured .LOOKUP 
assigns a channel to the magtape handler. Unpredictable results occur if 
this request is issued for a channel that was not opened with a non-file- 
structured .LOOKUP. The .SPFUN request has the following format: 

.SPFUN area,chan,#-20.,buf„blk 

- 20 is the code for the asynchronous directory request. 
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huf is the address of a seven-word block with the following format: 

Word Meaning 

0-2 Radix-50 representation of the file name. 

3 One of the following codes: 

3 for .LOOKUP 

4 for .ENTER 

4 Sequence number value. See the corresponding sections for 
.LOOKUP or .ENTER for complete information on the in- 
terpretation of this value. 



5,6 



Reserved. 



hlk is the address of a four-word error and status block used for returning 
.LOOKUP and .ENTER errors that are normally reported in byte 52. Only 
the first word of blk is used by this request. The other three words are 
reserved for future use and must be zero. When the first word of blk is 0, no 
error information is returned. This block must always be mapped when the 
program is running in the extended memory environment. Figure 10-2 
shows a programming example. 



Figure 10-2: Asynchronous Directory Operation Example 

ASYNCHRONOUS DIRECTORY OF'ERATIO MACRO V04.00 14-0CT-79 21!06!27 PAGE 1 



.TITLE ASYNCHRONOUiJ DIRECTORY OPERATION EXAMPLE ADO. MAC 



3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 

21 000000 
22 

23 000020 

24 000022 
25 

26 000056 
27 



177754 

000003 

000004 

000000 
000001 
000000 



103426 



103012 



start; 



.ENABL 
.MCALL 



LC 
.LOOKUP. 



^DEFINITIONS 



ASYREO 

LOOKUP 

ENTER 

CHAN 

FNF 

FSN 



= -20. 

= 3 

= 4 

= 
= 1 
= 



.SPFUN, .CLOSEf .PRINTr .EXIT 



^ASYNCHRONOUS REQUEST 

(CODE 

(LOOKUP CODE FOR ASYNCH 

(REQUEST 

(ENTER CODE FOR ASYNCH 

(REQUEST 

(USE CHANNEL 

(FILE NOT FOUND ERR 

(USE FOR FILE 

(SEQUENCE NUMBER 



( MAGTAPE HANDLER IS ASSUMED TO BE LOADED 

.LOOKUP *AREA>tCHANr*NFSBLK (OPEN A CHANNEL FOR 

(THE NEXT REQUEST 

BCS LOOKER (ERROR OCCURRED 

.SPFUN *AREAj*CHANf»ASYREQf#COMBLK» i*ERRBLK 

(DO A LOOKUP 

BCC FOUND (NO ERROR MEANS FILE 

(UAS FOUND 
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Figure 10-2: Asynchronous Direct Operation Example (Cont.) 



29 000060 



30 000066 

31 000070 

32 000074 
33 

34 000076 

35 000102 
36 

37 000104 

38 000110 
39 

40 000112 

41 

42 000116 

43 
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48 
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50 000144 
51 

52 
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000152 
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55 
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57 
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59 

60 
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62 000172 
000174 
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000200 

63 
64 
65 
66 

67 000202 

68 000244 

69 000257 
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71 

72 
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022767 
000001 
000104 
001411 
012700 
000276 
000410 

012700 
000202 
000405 

012700 
000244 
000402 

012700 
000257' 



♦FNF.ERRBLK 



052140 



000000 
000000 
000000 
023364 
053665 
100370 

000003 

000000 



000000 
000000 
000000 
000000 
000000 
000000 
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106 
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000000' 



CHP 

BEQ 
hOV 

BR 
LOOKER! MOV 

BR 
FOUND! MOM 

BR 
N0TFND5 MOV 

CLOSE! .PRINT 



.CLOSiE *CHAN 
.EXIT 

f riATA AREA 

AREA! .BLKK 6 

NFSBLK! .RAD50 /MT/ 



JFILE NOT FOUND ERROR? 



OK! 

NOK! 

ASYERR! 
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CLOSE 
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CLOSE 
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.WORD LOOKUP 
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(PRINT MESSAGE POINTED 
(TO BY RO 



(EMT ARGUMENT AREA 
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(STRUCTURED 
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(THIS IS THE FILE 

(SEQUENCE NUMBER FOR THE 
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LOOERRi .ASCrZ 
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.ASCIZ 

.ASCIZ 

.EVEN 

.LIST 

.END 



BEX 

'Non-fi le -structured .LOOKUP failed' 

'File found' 

'File not found' 

'Asynchronous reouest error' 

BEX 

START 



SYMBOL TABLE 

AREA 000130R 
ASYERR 000276R 
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CHAN = 000000 
CLOSE 000116R 



ERRBLK 
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000144R 
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OK 
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000202R 
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Figure 10-2: Asynchronous Direct Operation Example (Cont.) 

COMBLK 000154R LOOKER 000076R ...VI = 000003 

ENTER = 000004 LOOKUP= 000003 ...V2 = 000027 

. ABS. 000000 000 
000332 001 
ERRORS DETECTED! 

VIRTUAL MEMORY USED! 9216 WORDS ( 36 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 73 PAGES 
>ADO/L!TTM=ADO 

10.1.1.4 Issuing Hardware Handler Calls with the File Structure IVIodule — The 
magtape handler is designed to perform two distinct types of access. One 
type of access is file-oriented; it makes the magtape appear to be a disk. In 
other words, it makes the magtape as device-independent as possible. The 
other type of access allows access to the hardware commands such as read, 
write, space, and so on, but the programmer need not know whether the 
device is a TMll or TJU16, for example (see Section 10.1.2). 

When the handler accesses magtape using file-oriented commands, it keeps 
track of the file sequence number where the tape is positioned. Thus, it can 
optimize tape movement during file searches. When the handler accesses 
data in a magtape file using the .READx/.WRITx requests, it keeps track 
of the current block number as well as the last block number accessible. The 
block number argument can be used to simulate a random-access device 
even on files opened with .ENTER. 

The two access methods just described can be combined; that is, it is possi- 
ble to use hardware handler tape movement commands on a magtape file. 
However, doing so has the following implications: 

1. When the first hardware handler command is received, the stored file 
sequence number and block number information described above are 
erased and are not reinitialized until a .CLOSE and another file open- 
ing command have been performed. Note that the .CLOSE moves and, 
in the case of the file opened with .ENTER, writes the tape regardless 
of any commands that have been issued since the file was opened. Also 
note that the tape will no longer be an ANSI-compatible magtape. 
When the file is closed, the magtape handler cannot write the size of 
the file because the file size is lost to the handler. It writes a zero in its 
place. The file sequence number field will be correct. 

2. The only exception to the rule explained above occurs when you need 
to open the tape as file-structured and write data blocks that are not 
the standard 512-byte size that magtape .WRITx requests use. The 
magtape handler keeps track of the number of blocks written and the 
EOFl labels are correct as long as no commands other than the 
.SPFUN write command are used. If other commands are used, the file 
size is lost. 

NOTE 

DIGITAL recommends that programmers issue .SPFUN 
commands to a magtape file only for the case described in 2 
above. 
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10.1.2 Hardware Magtape Handler 

The hardware magtape handlers accept only hardware requests. These are 
applicable in I/O operations where no file structure exists. Any file struc- 
ture request you make to the hardware handler results in a monitor direc- 
tory I/O error. The hardware handler is a subset of the file structure 
magtape handler. 

If you do not need the extra file structure support, use the hardware 
handlers. Although the hardware handlers are part of the distribution kit, 
you must rename them in order to use them. Use a series of monitor com- 
mands similar to the following, vsrhich replace the file structure MT handler 
with the hardware MT handler. 

Command Action 

REMOVE MT Removes the file-structure handler. 

RENAME/SYS MT.SYS MTFS.SYS Saves the file structure handler. 

RENAME/SYS MTHD.SYS MT.SYS Creates the new hardware handler. 

INSTALL MT Installs the new handler. 

You access the hardware handler with non-file-structured .LOOKUP pro- 
grammed requests, with .SPFUN special function requests, and with 
.READ, .READC, .READW, .WRITE, .WRITC, .WRITW, and .CLOSE re- 
quests. The hardware handler can perform I/O operations on physical 
blocks, position the tape, and recover from errors. 

10.1.2.1 Exception Reporting — Those .SPFUN requests that are accepted 
by the hardware handler repc>rt end-of-file and hard error conditions 
through byte 52 in the system <:ommunication area. In addition, they use 
the argument normally used for a block number as a pointer to a four-word 
error and status block in order to return qualifying information about ex- 
ception conditions. When the block number argument is 0, no qualifying in- 
formation is returned. Note that the contents of these words are undefined 
when no exception conditions have occurred and the carry bit is not set. The 
block is defined as follows: words 1 and 2 are qualifying information; words 
3 and 4 are reserved for DIGITjAlL and must be 0. You need initialize words 
3 and 4 only once in your program. The system modifies words 1 and 2 only 
when it reports exception information. 

Qualifying information returned in the first word for the end-of-file 
condition is shown in Table 10-7. Note that the carry bit is set, and byte 52 
is zero. 

When a tape mark is detected during a spacing operation, the number of 
blocks not spaced is returned in the second word. 

EOT, tape mark, and BOT are returned as an EOF by the hardware 
handler. 

Qualifying information returned in the first word for the hard error condi- 
tion is shown in Table 10-8. No1:e that the carry bit is set, and byte 52 is 1. 
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Table 10-7: End-of-file Qualifying Information 

First Word 

Octal Code Meaning 



1 Tape before EOF only (tape mark detected). 

2 Tape before EOT only (no tape mark detected). 

3 Tape before EOT and EOF (tape mark detected). 

4 Tape before BOT (no tape mark detected). 



Table 10-8: Hard Error Qualifying Information 



First Word 

Octal Code Meaning 



No additional information (includes parity error and all others not listed 
below. Consult documentation for your particular tape drive for all possi- 
ble error conditions.) 

1 Tape drive not available. 

2 The controUer lost the tape position. When this error occurs, rewind or 
backspace the tape to a known position. 

3 Nonexistent memory was accessed. 

4 Tape is write-locked. 

5 The last block read had more information. The MM handler returns (in 
the second status word) the number of words not read. 

6 A short block was read. The second status word contains the difference 
between the number of bytes requested and the number of bytes read. 



The hardware handler issues a hard error if it receives any request other 
than non-file-structured .LOOKUP, .CLOSE, or any .SPFUN request not 
defined for the hardware handler. 

When a program runs in the XM environment, the status block for error 
reporting must be mapped at all times. 

10.1.2.2 Reading and Writing Physical Blocks — The hardware handler reads 
and writes blocks of any size. Requests for reading and writing a variable 
number of words are implemented through two .SPFUN codes. 

The .SPFUN request to read a variable number of words in a block has the 
following format: 

.SPFUN area,chan,#370,buf,wcnt,blk[,crtn] 

370 is the function code for a read operation. 

hlk is the address of a four-word error and status block used for returning 
the exception conditions. 
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crtn is an optional argument; that specifies a completion routine to be 
entered after the request executes. 

This request returns the errors shown in Table 10-9. Additional qualifying 
information for these errors is returned in the first two words of the blk 
argtiment status block. 

Table 10-9: .SPFUN Errors 



Byte 52 
Code 



First 
Word 
Code 



Qualifying Information 



EOF 
Value =0 



Hard error 
Value = 1 



1 Tape before EOF only (tape mark detected). 

2 Tape before EOT only (no tape mark detected).. 

3 Tape before EOF and EOT (tape mark detected). 

No additional information (consult documentation for your 
particular tape drive for all possible error conditions). 

1 Tape drive not available. 

2 The controller lost the tape position. 

3 Nonejcistent memory accessed. 

4 Tape is write-locked. 

5 The last block read had more information. The MM handler 
returns (in the second status word) the number of words not 
read. 

6 A short block was read. 

The second status word contains the difference between the 
number of words requested and the number read. 



The .SPFUN request to write a variable number of words to a block has the 
following format: 

.SPFUN area,chan,#371,buf,wcnt,blk[,crtn] 

371 is the function code for a 'ivrite operation 

This request returns the errors shown in Table 10-10. Additional qualifying 
information for these errors is returned in the first two words of the status 
block. 

NOTE 

The TJU16 tape drive can return a hard error if a write re- 
quest with a word count less than 7 is attempted. 

10.1.2.3 Spacing Forward and Backward — The hardware handler accepts a 
con;imand that spaces forward or backward block-by-block or until a tape 
mark is detected. When a tape mark is detected, the handler reports it along 
with the number of blocks not skipped. These commands can be used to 
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Table 10-10: .SPFUN Errors 



Byte 52 
Code 


First Word 
Code 


Qualifying Information 


EOF 
Value = 


1 
2 


Tape before EOF only (tape mark detected). 
Tape before EOT only (no tape mark detected). 




3 


Tape before EOF and EOT (tape mark detected). 


Hard error 
Value = 1 





No additional information (consult documentation 
for your particular tape drive for all possible error 
conditions.) 




1 


Tape drive not available. 




2 


The controller lost the tape position. 




3 


Nonexistent memory accessed. 




4 


Tape is write-locked. 



issue a space-to-tape-mark command by passing a number greater than the 
maximum number of blocks on a tape. The tape is left positioned after the 
tape mark or the last block passed. The two spacing requests have the 
following forms. 

The command to space forward by block has the following format: 
.SPFUN area,chan,#376„wcnt,blk[,crtn] 

376 is the function code for a forward space operation. 

went is the number of blocks to space past (must not exceed 65534). 

cHn is an optional argument that specifies a completion routine to be 
entered after the request executes. 

This request returns the errors shown in Table 10-11. Additional qualifying 
information for these errors is returned in the first two words of the status 
block. 

Table 10-11: .SPFUN Errors 

Byte 52 First Word 

Code Code Qualifying Information 



EOF 1 Tape before EOF only (tape mark detected). 

Value = 

2 Tape before EOT only (no tape mark detected). 

3 Tape before EOF and EOT (tape mark detected). 

The second word in the status block contains the 
number of blocks requested to be spaced (went), 
minus the number of blocks spaced if a tape mark or 
BOT is detected. Otherwise, its value is not defined. 
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Table 10-11: .SPFUN Errors (Cont.) 



Byte 52 
Code 



First Word 
Code 



Qualifying Information 



Hard error 
Valvie = 1 



No additional information (consult documentation 
for your particular tape drive for all possible error 
ccmditions). 

Tiipe drive not available. 

The controller lost the tape position. 



NOTE 

Due to hardware restrictions, DIGITAL recommends that 
no forward space commands be issued if the reel is posi- 
tioned past the EOT Eiarker. 

The format of the command tc> space backward by block is as follows: 

.SPFUN area,chan,#375„wcnt,blk[,ortn] 

375 is the function code for a backspace operation. 

This request returns the errors shown in Table 10-12. Additional qualifying 
information for these errors is returned in the first two words of the status 
block. 



Table 10-12: .SPFUN Errors 



Byte 52 
Code 



First Word 
Code 



Qualifying Information 



EOF 

Value = 



Hard error 
Vahie = 1 



Tape before EOF only (tape mark detected). 

Tape before EOT only (no tape mark detected). 

Tape before EOF and EOT (tape mark detected). 

Tape before EOT (no tape mark detected). 

Tlie second word in the status block contains the 
number of blocks requested to be spaced (went), 
minus the number of blocks spaced if a tape mark or 
HOT is detected. Otherwise, its value is not defined. 

No additional information (consult documentation 
for your particular tape drive for all possible error 
conditions). 

Tape drive not available. 

Tlie controller lost the tape position. 



Programming for Specific Devices 10-17 



10.1.2.4 Rewinding — The handler accepts a rewind command and rewinds 
the tape to BOT. The MT and MM handlers cannot accept other requests 
until the rewind operation is complete; the MS handler can. The rewind re- 
quest has the following format: 

.SPFUN area,chan,#373,„blk[,crtn] 

373 is the function code for the rewind operation. 

crtn is an optional argument that specifies a completion routine to be' 
entered after the request executes. 

This request returns the error shown in Table 10-13. Additional quahfying 
information is returned in the status block. 



Table 10-13: .SPFUN Errors 

Byte 52 First Word 

Code Code Qualifying Information 

Hard error No additional information (consult documentation 

Value = 1 for your particular tape drive for all possible error 

conditions). 

1 Tape drive not available. 



10.1.2.5 Rewinding and Going Off Line — This request is the same as rewind, 
except that it takes the tape drive off line and then rewinds to BOT. The 
handler is free to accept commands after the rewind is initiated. The rewind 
and go off Une request has the following format: 

.SPFUN area,chan,#372„,blk[,crtn] 

372 is the function code for the rewind and go off line operation. 

crtn is an optional argument that specifies a completion routine to be 
entered after the request executes. 

This request returns the same error code and qualifying information as the 
rewind request. 

10.1.2.6 Writing witli Extended Gap — This request permits you to write on 
tapes that have bad spots. It is identical to the write request except for its 
function code, which is 374. The errors are identical to those for the write 
request. 

10.1.2.7 Writing a Tape IVIark — The hardware handler accepts a request to 
write a tape mark. This request has the following format: 

.SPFUN area,chan,#377,„blk[,crtn] 

377 is the function code for the write tape mark operation. 
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This request returns the errors shown in Table 10-14. Additional qualifying 
information for these errors is returned in the first two words of the blk 
argument status block. 

Tablie 10-14: .SPFUN Errors 



Byte 52 
Code 


First Word 
Code 


Qualifying Information 


EOF 
Value = 


1 


Tape before EOF only (tape mark detected). 


Hard error 
Value = 1 





No additional information (consult documentation 
for your particular tape drive for all possible error 
conditions). 




1 


Tape drive not available. 




2 


The controller lost the tape position. 




4 


Tape is write-locked. 



10.1.2.8 Error Recovery — Any errors detected during spacing operations 
cause the recovery attempt to be aborted, and a hard (position) error is 
reported. 

Both the file structure handler and the hardware handler perform the 
following operations if a read parity error is detected. 

1. Backspaces over the block and rereads. When unsuccessful the pro- 
cedure is repeated until five read commands have failed. 

2. Backspaces five blocks, spaces forward four blocks, then reads the 
record. 

3. Repeats steps 1 and 2 eight times or until the block is read success- 
fully. 

The handler performs the following operations upon detection of a read 
after write (RAW) parity error. 

1. Backspaces over one block. 

2. Erases three inches of tapie and rewrites the block. In no case is an at- 
tempt made to rewrite the block over the bad spot, since, even if the at- 
tempt succeeds, the block could be unreUable and cause problems later. 

3. Repeats steps 1 and 2 if the read after write still fails. When 25 feet of 
erased tape have been written, a hard error is given. 

10.1.2.9 Non-File-Structured .LOOKUP Programmed Request — The hardware 
handler accepts a non-file-structured .LOOKUP request, a function that is 
necessary to open a channel to the device before any I/O operations can be 
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executed. It causes the hardware handler to mark the drive busy so that no 
other channel can be opened to that drive until a .CLOSE is issued. This re- 
quest has the following format: 

.LOOKUP area,chan,dblk,seqnum 

seqnum is an argument that specifies whether the tape is to be rewound. 
When this argument is 0, the tape is rewound. When this argument is - 1, 
the tape is not rewound; Table 10-15 shows the errors this request returns. 

Table 10-15: .LOOKUP Errors 
Byte 52 Code Meaning 

or 1 Not meaningful for this request. 

2 Device in use. The drive being accessed is already attached to another 
channel. 

3 Tape drive not available. 

4 Invalid argument detected. The file name was not 0, or the seqnum argu- 
ment was not or - 1. 



10.1.2.10 .CLOSE Programmed Request — The hardware handler accepts the 
.CLOSE request and causes the handler to mark the drive as available. This 
request has the following format: 

.CLOSE Chan 

10.1.2.11 Non-File-Structured .WRITx Programmed Requests — The hardware 
handler accepts .WRITx requests that write a variable number of words to 
a block on tape. The block number field is ignored. These requests have the 
following format: 

.WRITx area,chan,buf,wcnt[„crtn] 

These requests return the errors shown in Table 10-16. No additional quali- 
fying information is available. 

Table 10-16: .WRITx Errors 
Byte 52 Code Meaning 

The EOT marker has been detected. 

1 Hard error occurred on channel. 

2 Channel not open. 

10.1.2.12 Non-File-Structured .READx Programmed Requests — These requests 
read a variable number of words from a block on tape. They ignore the EOT 
marker and only report end-of-file when a tape mark is read. The block 
number field is ignored. The requests have the following format: 

.READx area,chan,buf,wcnt[„crtn] 
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These requests return the erroirs shown in Table 10-17. No additional quali- 
fying information is available. 

Table 10-17: .READx Errors 
By4;e 52 Code Meaning 

Attempt to read past a tape mark. Also generated by a block that is 
too large. 

1 Hard error occurred on channel. 

2 Channel not open. 



10.1.3 Transporting Tapes to RT-11 

RT-ll can read files written on other computer systems that support the 
ANSI standard labels. The following sections give a few examples of how to 
write ANSI tapes on some common DIGITAL PDP-11 operating systems. 
Keep in mind that there are other factors involved in addition to the label 
and format compatibility, including density, parity, and number of tracks. 
Consult the appropriate system documentation for complete information on 
using magtapes under the different operating systems. (See the RT-11 
System User's Guide for information on transporting tapes from RT-11 to 
otheir systems.) 

10,1.3.1 From RSTS/E — RSTS/E supports two types of magtape format, 
DOS- 11 and ANSI. In the following examples, dd represents the magtape 
handler name. In order to ensure that an ANSI file structure is written, 
issues the following commands: 



Commands Action 

ASSIGN ddn:.ANSI Allocates the device to the job 

and ensures that an ANSI file 



structure is used. 



RUN $PIP 



ddn:xxxxxx/ZE PIP initializes the tape; xxxxxx 

is the volume ID. 

Really zero ddn:? YES PIP prompts before initializ- 

ing the tape. 

PIP ddn: = TEST1.MAC,TEST2.MAC PIP copies files to the tape. 

DEASSIGN ddn: Deallocates the device. 



10.1.3.2 From RSX-IIM — RS^iC-llM needs the following commands to ac- 
cess a magtape: 
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Commands Action 

ALL ddn: Allocates a drive. 

INIT ddn:RTll Initializes the tape and gives 

the name RTll as the volume 
identification, 

MOU ddn:RTll Mounts the tape volume. 

PIP ddn: = [13,14]TEST1.MAC,TEST2.MAC 

Copies files to the tape. 

DM0 ddn:RTll Dismounts the tape volume. 

DEA ddn: Deassigns the drive. 



10.1.3.3 From RSX-11D and IAS — Use the following commands to write an 
ANSI tape on RSX-llD or IAS: 

Commands Action 

INIT ddn:RTll Initializes the tape and gives the 

name RTll as the volume 
identification. 

MOU ddn:RTll Mounts the tape volume. 

For RSX-llD, use PIP to write files to the tape; for IAS, use the COPY 
command. 

DM0 ddn:RTll Dismounts the tape volume. 

The contents of files written under the RSX-llD, RSX-llM, and IAS 
systems do not necessarily correspond to those types of data files under 
RT-11. For example, under RT-11, text files consist of stream ASCII data 
(carriage return and line feed characters are embedded in the text); the other 
operating systems use a different type of character storage. Be sure to pay 
attention to the contents of the files you need to transfer. 

When you write files to be read under RT-11, the only valid block size the 
utiUty programs use is 512 characters per block. However, the DIR pro- 
gram will list the directory of any ANSI compatible tape. 



10.1.4 Seven-Track Tape 

Seven-track tapes contain six data tracks and one parity track, so a max- 
imum of six data bits can be contained in one tape character. With seven- 
track tapes, the MT handler operates in either six-bit mode or core dump 
mode. Six-bit mode is not compatible with the data normally created by 
PDP-11 systems; it is provided for transferring data to or from other 
systems. In addition, file structure operations cannot be performed in this 
mode. With the density set at 200 or 556 bpi, the magtape always operates 
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in six-bit mode. Core dump moide is compatible with PDP-11 systems. At 
800 bpi, seven-track tape transfers can occur in either six-bit mode (SET 
MT: DENSE = 807) or core dumip mode (the default). Figure 10-3 illustrates 
the differences between six-bit mode and core dump mode. 

Figure 10-3: Seven-Track Tape 
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When reading in six-bit mode, the handler places each six-bit tape character 
right-justified in a PDP-11 byte; the high-order two bits of the byte are set 
to 0. When writing in six-bit mode, the handler writes the low-order six bits 
of a PDP-11 byte as the six data bits of a tape character; the high-order two 
bits of the PDP-11 byte are not transferred or affected. 

In core dump mode, each PDP-11 byte is split into two tape characters. In 
writing to the tape, the handler writes the low-order four bits of a PDP-11 
byte as the low-order four bits of the first tape character; the high-order 
four bits of the PDP-11 byte aie then written as the low-order four bits of 
the n(}xt tape character. The high-order two bits of each tape character are 
set to 0. In reading from the tape, the reverse process occurs. The low-order 
four bits of the first tape charsicter become the low-order four bits of the 
PDP-11 byte; the low-order fouir bits of the next tape character become the 
high-order four bits of the PDP-11 byte. The high-order two bits of each 
tape character are not involved in the transfer, although they are included 
in the parity calculation. Thus, in core dump mode, the actual number of 
tape characters read or written is twice the number of PDP-11 bytes re- 
quested to be transferred; this conversion is performed by the magtape con- 
troller. 
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10.2 Cassette Handler: CT 



The cassette handler can operate in two different modes: hardware mode 
and software mode. These names refer to the type of operation that can be 
performed on the device at a given time. Software mode is the normal mode 
of operation you use when you access the device through any of the RT-11 
utility programs. In software mode, the handler automatically attends to 
file headers and uses a fixed record length of 64 words to transfer data, (For 
more information on cassette structure, see Chapter 9). 

Hardware mode allows you to read or write any format, using any record 
size. In this mode, the handler interprets the word count as the physical 
record size. 

When the handlers are initially loaded by either the .FETCH programmed 
request or the monitor LOAD command, only software functions are per- 
mitted. To switch from software to hardware mode, issue either a rewind or 
a non-file-structured .LOOKUP. (A non-file-structured .LOOKUP is a 
.LOOKUP in which the first word of the file name is null.) 

In software mode, the following functions are permitted: 

Request Action 

.ENTER Opens new file for output. 

.LOOKUP Opens existing file for I/O. 

.DELETE Deletes an existing file. 

.CLOSE Closes a file opened with .LOOKUP or 

.ENTER. 

.READx/.WRITEx Performs data transfer requests. 



In .ENTER, .LOOKUP, and .DELETE, you can specify an optional file 
count argument, which results in the following actions: 

Argument Action 

A rewind is done before the operation. 

> No rewind is done. The value of the count is 

taken as a limit of how many files to look at 
before performing the operation. (For example, 
a count of 2 looks at two files at most. A count 
of 1 looks at only the next file.) 

<0 A rewind is done. The absolute value of the 

count is then used as the Umit. 

If the file indicated in the request is located before the limit is exhausted, 
the search succeeds at that point. 
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Consider the following example: 

.LOOKUP #AREA,#0,#PTR,#5 
BOS A1 



AREA: 


.BLKW 


10. 


PTR: 


.RAD50 


/CTO/ 




.RAD50 


/EXAMPLMAC/ 



In this case, the file count arguiment is + 5, indicating that no rewind is to 
be done and that CTO is to be searched for the indicated file 
EXAMPL.MAC. If the file is not found after four files have been skipped, 
or if an EOT occurs in that spac(J, the search is stopped, and the tape is posi- 
tioned either at EOT or at the start of the fifth file. If the named file is 
found within the five files, the tape is positioned at its start. If EOT is en- 
countered first, an error is generated. 

The following example performs a rewind, then uses a file count of five as in 
the previous example. 

.LOOKUP #AREA,#0,#PTR,#-- 5 



10.2.1 Handler Functions 

The following sections describes the functions performed by the cassette 
handler. 

10.2.1.1 .LOOKUP Request — If the file name (or the first word of the file 
name) is zero, the operation is considered to be a non-file-structured 
.LOOKUP. This operation puts the handler into hardware mode. A rewind 
is automatically done in this case. 

If the file name is not null, the handler tries to find the indicated file. The 
.LOOKUP request uses the optional file count argument described in Sec- 
tion 10.2. Only software functions are allowed. 

10.2.1.2 .DELETE Request — Th(; .DELETE request eliminates a file of the 
designated name from the device. The .DELETE request also uses the file 
count argument and can thus delete a numbered file as well as a named file. 
When a file is deleted, an unused space is created. However, it is not possi- 
ble to reclaim that space, as it is when the device is random-access. The 
space remains unused until the ^'^olume is reinitialized and rewritten. If a file 
name is not present, a non-file-structured .DELETE is performed and the 
tape is initialized. 

10.2.1.3 .ENTER Request — The .ENTER request creates a new file of the 
designated name on the device. This request uses the optional file count and 
can thus create a file by name or by number. If the request creates a file by 
name, the handler deletes any files of the same name. If the request creates 
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a file by number, the indicated number of files is skipped and the tape is 
positioned at the start of the next file. 

NOTE 

Care must be exercised in performing numbered .ENTER 
requests, as it is possible to create a file in the middle of ex- 
isting files and thus destroy the files from the next file to 
the end of the tape. 

It is also possible to create more than one file with the 
same name, since .ENTER only deletes files of the same 
name it encounters while passing down the tape. If an 
.ENTER is issued with a count greater than 0, no rewind is 
performed before the file is created. If a file of the same 
name is present at an earlier spot on the tape, the handler 
cannot delete it. A non-file-structured .ENTER performs 
the same function as a non-file-structured .LOOKUP but 
does not rewind the tape. Since both functions allow 
writing to the tape without regard for the tape's file struc- 
ture, they should be used with care on a file-structured 
tape. 

10.2.1.4 .CLOSE Request — The .CLOSE request terminates operations to a 
file on cassette and resets the handler to allow more .LOOKUP, .ENTER, or 
.DELETE requests. If a .CLOSE request is not performed on a file created 
with .ENTER, the EOT label wiU be missing and no new files can be created 
on that volume. In this case, the last file on the tape must be rewritten and 
closed to create a valid volume. 

10.2.1.5 .READ/.WRITE Requests - The .READ and .WRITE requests can 
be issued either in hardware or software mode. In software mode (file open- 
ed with .LOOKUP or .ENTER), records are written with a fixed size of 64 
words. The word count specified in the operation is translated to the correct 
number of records. On a .READ request, the user buffer is filled with zeroes 
if the word count exceeds the amount of data available. 

Following is a description of how the various arguments for .READ and 
.WRITE are used. 

1. Block number (blk) 

Only sequential operations are performed. If the block number is 0, the 
cassette is rewound to the start of the file. Any other block number is 
disregarded. 

2. Word count (went) 

If the word count is 0, the following conditions are possible: 

If the block number is nonzero, the operation is a file name seek. The 
block number is interpreted as the file count argument, as discussed in 
the example of .LOOKUP. The buffer address should point to the 
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Radix-50 equivalents of the device and file to be located. This feature 
essentially allows an asynchronous .LOOKUP to be performed. The 
standard .LOOKUP request does not return control to the user pro- 
gram until the tape is positioned properly, whereas this asynchronous 
version returns control immediately and interrupts when the file is 
positioned. 

"V'ou can then issue a synchironous, positively numbered .LOOKUP to 
the file just positioned, thus avoiding a long synchronous search of the 
tape. 

If the block number is 0, a cyclical redundancy check error occurs. 

10.2.2 Cassette Special Functions 

The following sections describe the vahd hardware mode functions for the 
handler and include examples of how to call them. In general, special func- 
tions are issued by using the .SPFUN programmed request. The special 
functions require a channel number as an argument. The channel must in- 
itially be opened with a non-file-structured .LOOKUP request, which places 
the handler in hardware mode. 

The general form of the .SPFUN request is: 

.SPFUN area,chan,func,buf,wcnt,blk,crtn 

func is the code for the function to be performed. 

10.2.2.1 Rewind — The rewind irequest rewinds the tape to its load point. 
This puts the unit in hardware mode in the same manner as a non-file- 
structured .LOOKUP, where any of the other functions can be performed. 
Unless a completion routine is specified, control does not return to the call- 
ing program until the rewind completes. This request has the following for- 
mat: 

.SPFUN area,#0,#373,#0,#0,#0,crtn 

crtn is a completion routine to Ibe entered when the operation is complete. 

10.2.2.2 Last File — The last file request rewinds the cassette and positions 
it immediately before the sentinel file (LEOT). This request has the follow- 
ing format: 

.SPFUIM area,#0,#377,#0,#0,#0[,crtn] 

10.2.2.3 Last Biocit — The last block request rewinds one record. This re- 
quest has the following format: 

.SPFUN area,#0,#376,#0,#0,#0,[,crtn] 

10.2.2.4 Next Fiie — The next file request spaces the cassette forward to the 
next file. This request has the following format: 
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.SPFU N area,#0,#375,#0,#0,#0[,crtn] 

10.2.2.5 Next Block — The next block request spaces the cassette forward 
by one record. This request has the following format: 

.SPFUN area,#0,#374,#0,#0,#0[,crtn] 



10.2.2.6 Write File Gap — The write file gap request terminates a file written 
by the calling program in hardware mode. The following example writes a 
file gap synchronously: 

.SPFUN area,#0,#372,#0,#0,#0 

The next two examples write file gaps asynchronously: 

.SPFUN area,#0,#372,#0,#0,#0,#1 
.SPFUN area,#0,#372,#0,#0,#0,crtn 

10.2.3 EOF Detection 

Since the cassette is a sequential device, the handler for this device cannot 
anticipate the number of blocks in a particular file, and thus cannot deter- 
mine if a particular read request is attempting to read past the end of the 
file. Programs can use the following procedures to determine if the handler 
has encountered EOF in either software or hardware mode. 

In software mode, if EOF is encountered during a read and some data is 
read, the cassette handler zero-fills the rest of the buffer and returns to the 
program. The next read attempted on that channel returns with the carry 
bit set and with the error byte (byte 52) set to indicate an attempt to read 
past EOF. 

In hardware mode, the cassette handler does not report EOF as it does in 
software mode. The best way that programs can determine if a cassette 
read has encountered a file gap is to check the device status registers after 
each hardware-mode read is complete. The following example shows how to 
check EOF and EOT bits. 



TAGS = 177500 
TAEOF = 4000 
TAEOT = 20000 



TA11 CSR 

EOF BIT IN TAGS 

EOT BIT IN TAGS 



.READW #AREA,#CHNL,#BUFF,#400,BLKNUM 







;READ FROM CT 


BCS 


EMTERR 


;TEST ERRORS 


TST 


@#TAGS 


;ERROR BIT SET IN 
TAGS? 


BPL 


NOERR 


;IF PLUS, NO 


BIT 


#TAEOF,@#TACS 


;YES; WAS IT EOF? 


BNE 


EOF 


;IF NE, YES 
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EOF: . ;EOF ENCOUNTERED 

. ; BOTH THE EOF AND EOT BITS CAN BE CHECKED: 

BIT #MTSEOF + MTSEOT,@#MTS ;MT EOF OR EOT? 

BIT #TAEOF + TAEOT,@#TAEOT ;CT EOF OR EOT? 

10.3 Diskette Handlers: DX and DY 

The .SPFUN request permits reading and writing of absolute sectors on the 
diskettes. The DY handler accepts an additional .SPFUN request to deter- 
niin(} the size, in 256-word blocks, of the volume mounted in a particular 
unit, On double-density diskettes, sectors are 128 words long. RT-11 nor- 
mally reads and writes them in groups of two sectors. On single-density 
diskettes, sectors are 64 words long. RT-11 reads and writes them in 
groups of four sectors. Sectors can be accessed individually through the 
.SPFUN request. The format of the request is as follows: 

.SPFUN area,chan,func,buf,wcnt,blk,crtn 

func is the code for the function to be performed. The codes and functions 
are as follows: 

Code Function 

377 Read physical sector 

376 Write physical sector 

375 Write physical sector with deleted data mark 

374 Reserved 

373 Determine device size, in 256-word blocks, of volume 

(DY only) 

6m/ for function codes 377, 376, and 375 is the location of a 129-word buffer 
(for double-density diskettes) or a 65-word buffer (for single-density 
diskettes). The first word of the buffer, the flag word, is normally set to 0. 

If the first word is set to 1, a njad on a physical sector containing a deleted 
data mark is indicated. The actual data area of the buffer extends from the 
second word to the end of the buffer. 

buf for function code 373 is the location of a one-word buffer in which the 
size of the volume in the specified unit is returned. (For single-density 
diskettes, 494 is returned. For double-density diskettes, 988 is returned.) 

went for functions 377, 376, and 375 is the absolute track number, 
through 76, to be read or written. 

went for function 373 is reserved and should be set to 1. 

hlk for functions 377, 376, and 375 is the absolute sector number, 1 through 
26, to be read or written. 

blk for function 373 is reserved and should be set to 0. 

The diskette should be opened with a non-file-structured .LOOKUP. Note 
also that the buf, went, and blk arguments have different meanings when 
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used with diskettes. The following example performs a synchronous sector 
read from track 0, sector 7, into a 65-word area called BUFF. 

.SPFUN #RDUST,#377,#BUFF,#0,#7,#0 

Each DX and DY handler can support two controllers, and each controller 
supports two drives. For example, if the RXOl handler is created through 
system generation to support two controllers, it will support four devices: 
DXO, DXl, DX2, and DX3. DXO and DXl are drives and 1 of the stan- 
dard diskette at vector 264 and CSR 177170. DX2 and DX3 are drives and 
1 of the other controller. Note that only one I/O process can be active at one 
time, even though there are two controllers. Overlapped I/O to the handler 
is not permitted. 

10.4 Card Reader Handler: CR 

The card reader handler can transfer data either as ASCII characters in 
DEC 026 or DEC 029 card codes (see Table 10-18) or as column images con- 
trolled by the SET command (see the RT-11 System User's Guide). In 
ASCII mode (SET CR: NOIMAGE), invalid punch combinations are decod- 
ed as the error character 134 octal, which is a backslash. In IMAGE mode, 
no punch combination is invaUd; each column is read as 12 bits of data 
right-justified in one word of the input buffer. The handler continues 
reading until the transfer word count is satisfied or until a standard EOF 
card is encountered (12-11-0-1-6-7-8-9 punch in column 1; the rest of the card 
is arbitrary). On EOF, the buffer is filled with zeroes and the request ter- 
minates successfully; the next input request from the card reader gives an 
EOF error. Note that if the transfer count is satisfied at a point that is not a 
card boundary, the next request continues from the middle of the card with 
no loss of information. If the input hopper is emptied before the transfer re- 
quest is complete, the handler hangs until the hopper is reloaded and the 
START button on the reader is pressed again. The transfer then continues 
until completion or until another hopper-empty condition exists. EOF is not 
reported on the hopper-empty condition. The handler hangs if the hopper 
empties during the transfer, regardless of the status of the SET CR: 
HANG/NOHANG option. No special action is required to use the card 
reader handler with the CMll mark sense card reader. The program should 
take into account the fact that mark sense cards can contain fewer than 80 
characters. Note also that when the CR handler is set to CRLF or TRIM 
and is reading in IMAGE mode, unpredictable results can occur. 

The card reader handler uses the blk argument of the ,RE ADx programmed 
request to determine if a new card should be read. The format of the request 
is as follows: 

.READx area,chan,buf,wcnt,blk 

If blk is 0, a new card is read and the word count argument is fiUed by 
characters on that card. Subsequent cards are read, if necessary, to com- 
plete the word count. If blk is nonzero, the word count argument is first 
satisfied by characters remaining from a previous card read request, and 
more cards are read, if necessary, to satisfy the count. 
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Table 10-18: DEC 026/DEC 029 Card Code Conversions 
Zone Digit Octiitl Character 



Name 



none 



12 



11 





none 


04CI 




1 


061 




2 


062 




3 


063 




4 


064 




5 


065 




6 


066 




7 


067 


(DEC 029) 


none 


046; 


(DEC 026) 




053 




1 


101 




2 


102 




3 


103 




4 


104 




5 


105 




6 


106 




" 7 


107 




none 


055 




1 


112 




2 


113 




3 


114 




4 


115 




5 


116 




6 


117 




7 


120 




none 


060 




1 


057 




2 


123 




3 


124 




4 


125 




5 


126 




6 


127 




7 


130 




none 


70 




1 


140 


<DEC 029) 


2 


072 


(DEC 026) 




137 


(DEC 029) 


3 


043 


{DEC 026) 




075 




4 


100 


[DEC 029) 


5 


047 


[DEC 026) 




136 


(DEC 029) 


6 


075 


(DEC 026) 




047 


(DEC 029) 


7 


042 


(DEC 026) 




134 



1 

2 
3 
4 
5 
6 
7 

& 

+ 

A 
B 
C 
D 

E 
F 
G 



J 
K 

L 
M 
N 
O 
P 



/ 

s 

T 

U 
V 

w 

X 

8 

\ 



SPACE 
digit 1 
digit 2 
digits 
digit 4 
digit 5 
digit 6 
digit 7 

ampersand 
plus sign 

upper-case A 
upper-case B 
upper-case C 
upper-case D 
upper-case E 
upper-case' F 
upper-case G 

minus sign 
upper-case J 
upper-case K 
upper-case L 
upper-case M 
upper-case N 
upper-case O 
upper-case P 

digit 
slash 

upper-case S 
upper-case T 
upper-case U 
upper-case V 
upper-case W 
upper-case X 

digits 
accent grave 
colon 
backarrow 

(underscore) 
number sign 
equal sign 
commercial "at" 
single quote 
uparrow 

(circumflex) 
equal sign 
single quote 
double quote 
backslash 
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Table 10-18: DEC 026/DEC 029 Card Code Conversions (Cont.) 

Zone Digit Octal Character Name 



12-11 



12-0 



12-8 



(DEC 029) 
(DEC 026) 

(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 
(DEC 029) 
(DEC 026) 



12-9 



11-0 



11-8 



(DEC 029) 
(DEC 026) 



none 
2 

7 

none 

1 

2 

3 

4 

5 

6 

7 

none 

1 

2 

3 

4 

5 

6 

7 

none 
2 

3 
4 

5 

6 

7 

none 

1 

2 

3 

5 

7 

none 

1 

2 

3 

4 

5 

6 

7 

none 
2 



071 
026 
004 

174 
152 
153 
154 
155 
156 
157 
160 

173 
141 
142 
143 
144 
145 
146 
147 

110 
133 
077 
056 
074 
051 
050 
135 
053 
074 
041 

111 
001 
002 
003 
Oil 
177 

175 
176 
163 
164 
165 
166 
167 
170 

121 
135 
072 
044 



9 
CTRL/V 


digit 9 

SYN 


CTRL/D 


EOT 


1 


vertical bar 


J 


lower-case J 


k 


lower-case K 


1 


lower-case L 


m 


lower-case M 


n 


lower-case N 





lower-case 


P 


lower-case P 


a 


open brace 
lower-case A 


b 


lower-case B 


c 


lower-case C 


d 


lower-case D 


e 


lower-case E 


f 


lower-case F 


g 


lower-case G 


H 

[ 
? 

< 

) 
( 
] 


upper-case H 

open square bracket 

question mark 

period 

open angle bracket 

close parenthesis 

open parenthesis 

close square bracket 


+ 
< 
! 


plus sign 

open angle bracket 

exclamation mark 


I 
CTRL/A 


upper-case I 
SOH 


CTRL/B 


STX 


CTRL/C 


ETX 


CTRL/I 


HT 




DEL 




close brace 


r^j 


tilde 


s 


lower-case S 


t 


lower-case T 


u 


lower-case U 


V 


lower-case V 


w 


lower-case W 


X 


lower-case X 



Q 



upper-case Q 

close square bracket 

colon 

dollar sign 
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Table 10-18: DEC 026/DEC 029 Card Code Conversions (Cont.) 

Zone Digit Octal Character Name 





4 


052 


* 


asterisk 


(DEC 029) 


5 


051 


) 


close parenthesis 


(DEC 026) 




133 


I 


open square bracket 


(DEC 029) 


6 


073 


1 


semi-colon 


(DEC 026) 




07(5 


> 


close angle bracket 


(DEC 029) 


7 


136 


* 


uparrow 
(circumflex) 


(DEC 026) 




046 


& 


ampersand 


11-9 












none 


122 


R 


upper-case R 




1 


021 


CTRL/Q 


DCl 




2 


022 


CTRL/R 


DC2 




3 


023 


CTRL/S 


DC3 




6 


010 


CTRL/H 


BS 


0-8 












null 


131 


Y 


upper-case Y 


(DEC 029) 


2 


134 


\ 


backslash 


(DEC 026) 




073 


J 


semi-colon 




3 


054 


» 


comma 


(DEC 029) 


4 


045 


% 


percent sign 


(DEC 026) 




050 


( 


open parenthesis 


(DEC 029) 


5 


137 


— 


backarrow 
(underscore) 


(DEC 026) 




042 


" 


double quote 


(DEC 029) 


6 


076 


> 


close angle bracket 


(DEC 026) 




043 


# 


number sign 


(DEC 029) 


7 


077 


? 


question mark 


(DEC 026) 




045 


% 


percent sign 


0-9 












null 


132 


Z 


upper-case Z 




5 


012 


CTRL/J 


LF 




6 


027 


CTRL/W 


ETB 




7 


033 




ESC 


9-8 












4 


024: 


CTRL/T 


DC4 




5 


025 


CTRL/U 


NAK 




7 


032 


CTRL/Z 


SUB 


12-9-8 












3 


013 


CTRL/K 


VT 




4 


014 


CTRL/L 


FF 




5 


015 


CTRL/M 


CR 




6 


016 


CTRL/N 


SO 


11-9-8 


7 


017 


CTRL/0 


SI 




none 


030 


CTRL/X 


CAN 




1 


031 


CTRL/Y 


EM 




4 


034 


CTRL/\ 


FS 




5 


035 


CTRL/] 


GS 




6 


036 


CTRL/* 


RS 




7 


037 


CTRL/_ 


US 


0-9-8 












5 


005 


CTRL/E 


ENQ 




6 


006 


CTRL/F 


ACK 




7 


007 


CTRL/G 


BEL 



Programming for Specific Devices 10-33 



Table 10-18: DEC 026/DEC 029 Card Code Conversions (Cont.) 



Zone 



Digit 



Octal 



Character 



Name 



12-0-8 

12-0-9 

12-11-8 

12-11-9 

11-0-8 

11-0-9 

12-11-9-8 

12-0-9-8 



none 


150 


none 


151 


none 


161 


none 


162 


none 


171 


none 


172 


1 


020 


1 


000 



h 
i 

q 

r 

y 

z 



lower-case H 
lower-case I 
lower-case Q 
lower-case R 
lower-case Y 
lower-case Z 



CTRL/P DLE 



NUL 



10.5 High-speed Paper Tape Reader and Punch: PC 

RT-ll provides support for the PRll High Speed Reader and the PCll 
High Speed Reader/Punch through the PC handler. The PC handler 
distributed with RT-ll supports both the paper tape reader and punch. A 
handler supporting only the paper tape reader can be created through 
system generation. The PC handler does not print an uparrow (^) on the ter- 
minal when it is entered for input the first time, as did the PR handler for 
earlier versions of RT-ll. The tape must be in the reader when the com- 
mand is issued, or an input error occurs. This prohibits any two-pass opera- 
tions from using PC as an input device. For example, linking and assembl- 
ing from PC does not work; an input error occurs when the second pass is 
initiated. The correct procedure is to transfer the paper tape file to disk or 
DECtape and then perform the operation on the new file. 

On input, the PC handler zero-fills the buffer when no more tape is available 
to read. On the next read request to the PC handler, the EOF bit is set and 
the carry bit is set on return from the I/O completion. 

10.6 Console Terminal Handler: TT 

The console terminal can be treated as a peripheral device by using the TT 
handler. Observe the following conventions and restrictions: 

1. An uparrow (') is typed when the handler is ready for input. 

2. CTRL/Z can be used to specify the end of input to TT. No carriage 
return is required after the CTRL/Z. If CTRL/Z is not typed, the TT 
handler accepts characters until the word count of the input request is 
satisfied. 

3. CTRL/0, typed while output is directed to TT, causes an entire output 
buffer (all characters currently queued) to be ignored. 

4. A single CTRL/C typed while typing input to TT causes a return to the 
monitor. If output is directed to TT, a double CTRL/C is required to 
return to the monitor if FB is running. If the SJ monitor is running, 
only a single CTRL/C is required to terminate output. 
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5. The TT handler can be in use for only one job (foreground or 
background) at a time, and for only one function (input or output) at a 
time. The terminal communication for the job not using TT is not af- 
fected at all. 

6. You can type ahead to TI'; characters are obtained from the input ring 
buffer before the keyboard is referenced. The terminating CTRL/Z can 
also be typed ahead. 

7. If the mainline code of a job is using TT for input, and a completion 
routine issues a .TTYIN request, typed characters are passed un- 
predictably to the .TTYIN and TT. 

8. If a job sends data to TT for output and then issues a .TTYOUT re- 
quest or a .PRINT request, the output from the latter is delayed until 
the handler completes its transfer. If a TT output operation is started 
when the monitor's terminal output ring buffer is not empty (before 
the print-ahead is complet;e), the handler completes the transfer opera- 
tion before the buffer contents are printed. 

10.7 RK06/07 Disk Handler: DM 

The RK06/07 disk handler has some features that are not standard for most 
RT-11 handlers. Among these nonstandard features are the following: 

1. Support of bad block replacement 

2. .SPFUN requests to read and write absolute blocks on disk 

3. .SPFUN request to initialize the bad block replacement table 

4. .SPFUN error return information 

5. .SPFUN request to determine the size of a volume mounted in a par- 
ticular device unit. (The ][IK06 and RK07 disks share the same con- 
troller and handler. The R,K07 has twice as many blocks as the RK06 
volume.) 

10.7.1 Bad Block Replacement 

The last cyUnder of the RK06 sind RK07 disks is used for bad block replace- 
ment and error information. RT-11 supports a maximum of 32 replaceable 
bad blocks on these disks. The bad block information is stored in block 1 on 
track 0, cylinder 0, of the disk. The replacement blocks are stored on tracks 
and 1 of the last cylinder. A bad block replacement table is created in 
block 1 of the disk by the DUF' utility program when the disk is initialized. 
When a bad block is encountered and the table is not present in the handler 
from the same volume, the DM handler reads a replacement table from 
block 1 of the disk and stores it in the handler. 

When a bad sector error (BSE) or header vaUdity error (HVRC) is detected 
during a read or write, the DIVI handler replaces the bad block with a cor- 
responding good block from the replacement tracks. The bad block replace- 
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ment feature of RT-11 requires blocks through 5 and tracks and 1 of the 
last cylinder to be good. This procedure causes an I/O delay since the 
read/write heads must move from their present position on the disk to the 
replacement area, and back again. 

If this I/O delay cannot be tolerated, the disk can be initialized without bad 
block replacement. In this case, bad blocks are covered by .BAD files. 
Neither the bad blocks nor the replacement tracks will be accessed. 

You determine at initialization time whether to cover bad blocks with .BAD 
files or to create a replacement table for them and substitute good blocks 
during I/O transfers. The advantage of using bad block replacement is that 
it makes a disk with some bad blocks appear to have none. On the other 
hand, covering bad blocks with .BAD files fragments the disk. Because 
RT-11 files must be stored in contiguous blocks, this fragmentation limits 
the size of the largest file that can be stored. 

Only BSE and HVRC errors trigger the DM handler's bad block replace- 
ment mechanism. If a bad block develops that is not a BSE or HVRC error, 
the disk must be reformatted to have this new block included in the replace- 
ment mechanism. Reformatting should detect the new bad block, mark it so 
that it generates a BSE or HVRC error, and add the block number to the 
bad block information on the disk. The disk should then be initialized to add 
the bad block to the replacement table. 

The monitor file cannot reside on a block that contains a BSE error if you 
are using bad block replacement. If this condition occurs, a boot error 
results when you bootstrap the system. In this case, move the monitor so 
that it does not reside on a block with a BSE error. 

10.7.2 .SPFUN Requests 

The RK06/07 handler accepts the .SPFUN programmed request with the 
following function codes: 

Code Action 

377 Read operation without doing bad block replacement; 

returns definitive error data. 

376 Write operation without doing bad block replacement; 

returns definitive error data. 

374 Re-read the bad block replacement table in the handler (the 

program changed it). 

373 Determine the size, in 256-word blocks, of a particular 

volume. 

The format of the .SPFUN request is the same as explained in the RT-11 
Programmer's Reference Manual, except as follows: for function codes 377 
and 376, the buffer size for reads and writes must be one word larger than 
required for the data. The first word of the buffer contains the error infor- 
mation returned from the .SPFUN request. This information is returned for 
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a .SPFUN read or write, and the data transferred follows the error informa- 
tion. The error codes and information are as follows: 

Code IVleaning 

100000 The I/O operation is successful. 
100200 A bad block is detected (BSE error). 

100001 An ECC error is corrected. 

100002 An error was recovered on a retry. 

100004 An error was recovered through an offset retry. 

100010 An error was recovered after recalibration. 

1774xx An error was not recovered. 

For function code 374, the huf, went, and blk arguments should be 0. For 
function code 373, huf is a one-word buffer where the size of the specified 
volume in 256-word blocks is re1:urned. The went argument should be 1, and 
the blk argument should be 0. 



10.8 RL01/02 Disk Handler: DL 

The RLOl/02 disk handler includes the following special features: 

1. .SPFUN requests to read and write absolute blocks on the disk 
(without invoking the bad block replacement scheme) 

2. Support of automatic bad block replacement 

3. .SPFUN request to initialize the bad block replacement table 

4. .SPFUN request to determine the size of a volume mounted in a par- 
ticular device unit 

The codes for the .SPFUN requests are as follows: 

Code Action 

377 Read operation without doing bad block replacement; 

returns definiti\'e error data. 

376 Write operation without doing bad block replacement; 

returns definitive error data. 

374 Re-read the bad block replacement table in the handler (the 

program changed it). 

373 Determine the size, in 256-word blocks, of a particular 

volume. 

Unlike the DM handler, the read and write .SPFUN requests for the DL 
handler do not return an error status in the first word of the buffer. 
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Bad block replacement for the RLOl and RL02 is similar to the bad block 
support for the RK06 and RK07. However, the RLOl and RL02 generate 
neither the bad sector error (BSE) nor the header validity error (HVRC). 
Therefore, the handler must check the bad block replacement table for each 
I/O transfer. Since the table is always in memory as part of the DL handler, 
the I/O delay is not significant. 

The last track of the RLOl/02 disk contains a table of the bad sectors that 
were discovered during manufacture of the disk. The 10 blocks preceding 
this table (the last 10 blocks in the second- to-last track) are set aside for bad 
block replacements. The maximum number of bad blocks — 10 — is defined 
in the handler. 

As with the RK06 and RK07, you determine at initialization time whether 
to cover bad blocks with .BAD files or create a replacement table for them 
and substitute good blocks during I/O transfers. The advantage of using 
bad block replacement is that it makes a disk with some bad blocks appear 
to have none. On the other hand, covering bad blocks with .BAD files 
fragments the disk. Because RT-11 files must be stored in contiguous 
blocks, this fragmentation limits the size of the largest file that can be 
stored. 

The monitor file cannot reside on a block that contains a replaced block if 
you are using bad block replacement. If this condition occurs, a boot error 
results when you bootstrap the system. In this case, move the monitor so 
that it does not reside on a block with an error. 

If you specify the /REPLACE option during initialization of an RLOl/02 
disk, DUP scans the disk for bad blocks. It merges the scan information 
with the manufacturing bad sector table, allocates a replacement for each 
bad block, and writes a table of the bad blocks and their replacements in the 
first 20 words of block 1 of the disk. Block 1 is a table of two-word entries. 
The first word is the block number of a bad block; the second word is its 
allocated replacement. The last entry in the table is 0. The entries in the 
table are in order by ascending bad block number. A sample table is shown 
in Figure 10-4. 

Figure 10-4: Bad Block Replacement Table 



BAD BLOCK 


12 


WORDO 


ITS REPLACEMENT 


10210 


BAD BLOCK 


37 


WORD 2 


ITS REPLACEMENT 


10211 


BAD BLOCK 


553 


WORD 4 


ITS REPLACEMENT 


10212 


END OF LIST 





WORD 6 
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The handler contains space to hold a resident copy of the bad block table for 
each unit. The amount of space eillocated is defined by the SYSGEN condi- 
tional DL$UN, which represents the number of RLOl units to be supported. 
The value defaults to 2 if it is not defined. The handler reads the disk copy 
of the table into its resident area under the following three conditions: 

1. If a request is passed to the handler and the table for that unit has not 
been read since the handler was loaded into memory. 

2. If a request is passed to the handler and the handler detects Volume 
Check drive status. This status indicates that the drive spun down and 
spun up again, which means that the disk was probably changed. 

3. If an .SPFUN 374 request is passed to the handler. This special func- 
tion is used by DUP when it initializes the disk table to ensure that the 
handler has a valid resident copy. 



10.9 Null Handler: NL 



The null handler accepts all read! and write requests. On output operations, 
this handler acts as a data sink. When a prograift calls NL, the handler 
returns immediately to the moniitor indicating that the output is complete. 
The handler returns no errors and causes no interrupts. On input operations 
NL returns an immediate EOF indication for all requests; no data is 
transferred. Hence, the contents of the input buffer are unchanged. 



10.10 DECtape II Handler: DD 



DECtape II is a random-access mass storage device that uses DECtape II 
magn<3tic tape data cartridges. RT-11 supports this device as a file- 
structured random-access device and as a system device. The following sec- 
tions describe some general characteristics of DECtape II. 

10.10.1 Write-Protect Feature 

Each cartridge has a write-protect tab (the word RECORD and an arrow are 
embossed on the tab). To write enable the cartridge, sUde the tab in the 
direction of the arrow. Slide the tab in the other direction to write protect 
the cartridge. You can also remove the tab altogether to permanently write 
protec;t the cartridge. 

10.10.2 Data Storage 

Cartridges have two magnetic tape tracks. DECtape II writes data in the 
same direction on each track and stores data in data records. It writes data 
records in a specific sequence and pattern; to write an entire cartridge, for 
example, it: 

1. W^rites alternate data records on the first track 

2. Rewinds to return to the bieginning of tape (BOT) mark 
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3. Writes data records skipped on the first pass 

4. Rewinds 

5. Writes alternate data records on the second track 

6. Rewinds 

7. Writes data records skipped on the first pass of the second track 

Figure 10-5 illustrates this interleaved format. 
Figure 10-5: DECtape II Tape Format 



TRACK 2// BOT 



TRACK 1 W BOT 




RT-11 accesses blocks, which on DECtape II consist of four records. Each 
cartridge stores 512 blocks, each block containing 256 words (64 words per 
record). 

In some circumstances, DECtape IFs interleaved tape format may adverse- 
ly affect performance. If, for instance, the monitor file on a system volume 
happened to overlap from the end of tape to the beginning of tape, the 
number of rewinds would increase and, consequently, seek times would in- 
crease. Following the suggestions in the next section can help you to avoid 
such overlap. 

10.10.3 Adding Bad Blocks to Avoid Excessive Rewinds 

If your system volume is a DECtape II cartridge, you may encounter per- 
formance problems (slow response time) due to excessive rewinds of the 
magnetic tape. You can actually improve system performance by creating 
dummy bad blocks in strategic locations. Performance degradation occurs 
when a file (particularly a monitor file) overlaps from the end of tape to the 
beginning of tape — for example, it extends from the last portion of the se- 
cond pass on track 1 to the first portion of the first pass on track 2. Slow 
response time results from the specific sequence and pattern in which DEC- 
tape II wiites data records on the cartridge. 
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You can avoid this overlap by creating dummy bad blocks in three loca- 
tions. (Figure 10-6 illustrates tltie locations of blocks on the tape.) Use DUP 
to create a bad block at the bej^nning of the second pass on track 1 (block 
128.), at the beginning of the first pass on track 2 (block 256.), and at the 
beginning of the second pass on track 2 (block 384.). In this way, you can 
prevent the system from writing across rewinds, since RT-11 requires 
contiguous free space in which to write files. However, this technique 
prevents you from creating any file over 127 blocks long, and also increases 
fragmentation. 

Figure 10-6: Bad Block Locations on DECtape II 



TRACK 2 \\ BOT 




TRACK 1 // BOT 
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Appendix A 

RK, DX, and PC Device Handlers 



This appendix contains commented listings of the RK, DX, and PC devices. 
Figure A-1 shows the RK (RK05 disk) handler, which is relatively 
straightforward; Figure A-2 shows the DX (single-density diskette) 
handler, which is more complex than RK since it involves intricate calcula- 
tions and uses a silo (a special buffer in the device itself); Figure A-3 shows 
the PC (papertape contraption) handler, a handler for a character-oriented 
device. For information on writing a device handler, read Chapter 7. 

The listings in the appendix were produced by assembling the conditional 
file CND.M AC together with the handler source files. The command strings 
to pi-oduce these assemblies a]id listing files are as follows: 

Keyboard monitor command: 

MACRO/LIST:dd.LST/NOOBJECT/SHIOW:ME:TTM CND + dd 

MA(I!RO program commands: 

R MACRO 
,dd/L:ME:TTM = CND,dd 

dd represents the two-charact«}r device handler name. 

In all Ustings, comments that sire part of the source file consist of uppercase 
characters; each line begins \(^ith a semicolon (;). The source file text is 
shown in dot-matrix typeface. Explanatory comments that were added as 
documentation in this appendiix are upper- and lower-case characters, and 
are p)rinted in regular typeface:. 

The file CND.MAC was created especially for these examples. It was 
assembled together with the handler source files to produce code for the 
three system generation conditions: memory management, error logging, 
and device time-out. Normally, you assemble a device handler file with the 
system conditional file, SYCND.MAC, to ensure that the handler has the 
same system generation parameters as the current monitor. 

Figure A-1: RK Disk Handler 

RK05 y04.00 MACRO V04 . 00 17-0CT-79 23:30:37 
TABLt; OF CONTENTS 

:i- 1 MACROS AND DEFINITIONS 

S- 1 riRIVER ENTRY 

(>- 1 INTERRUPT ENTRY POINT 

ti- 1 BOOTSTRAP DRiyER 

1 (CONDITIONAL FILE FOR HANDLER EXAMPLES 

2 i 

3 (CND.MAC 
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4 

5 

6 

7 

8 

9 

10 

U 

12 

13 



S9/4/79 JDC 

i 

iASSEMBLE WITH HANDLER 

flB-BIT I/Of TIME-OUT> 

(FOR HANDLER. 



000001 


HMG»T 


= 1 


000001 


ERL$G 


= 1 


000001 


TIMilT 


= 1 



.MAC FILE 
AND ERROR 



TO enable: 

L0GGIN(3 



fl8-BIT I/O 
(ERROR LOGGING 
(TIME-OUT 



1 

2 

3 

4 

5 

6 

7 

B 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 



TITLE RK05 V04.00 
IDENT /V04.00/ 
RT-U DISK (RKin HANDLER 

COPYRIGHT (C) 1979 BY 
DIGITAL EQUIPMENT CORPORATIONi MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE 
USED AND COPIED ONLY IN ACCORDANCE WITH THE 
TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF 
THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY 
OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND 
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED, 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE: 
WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS 
A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

DIGITAL ASSUMES " NO RESPONSIBILITY FOR THE USE OR 
RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT 
SUPPLIED BY DIGITAL. 

.SBTTL MACROS AND DEFINITIONS 



Preamble Section 



Each macro you use in the handler requires the .MCALL statement, as line 
3 shows. Since .DRDEF issues most of the .MCALL statements for you, 
you need issue only the .MCALL for .DRDEF, and for .SYNCH if you plan 
to use it. 



.MCALL .DRDEF 



The .DRDEF macro performs most of the work of the preamble section: 



5 000000 



.DRDEF RKj0fFILST»r4800. r 177400 i 220 



The .DRDEF macro generates the .MCALL statements for the other 
system macros: 

.MCALL .DRASTj .DRBEGr .DRBOTf .DRENDf .DRFIN5 .DRSET, 
.MCALL .DRVTB, .FORK. .QELDF 

The code in this handler contains many conditional assembly directives. 
They test for the presence or absence of time-out support, extended 
memory support, and error logging. Code is generated differently depend- 
ing on which of those system generation features are present in the system. 
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If there is no conditional file assembled with the handler file, the condi- 
tionals are turned off by the folilowing lines of code. For this example, the 
three following conditionals weire set to 1 by the file CND.MAC. 





.IIP 


NIiF TIMtIT, TIh«IT-0 


000001 


.IIF 


HE TIMtir, TIM*IT=1 




.IIF 


NIiF MhGtT, MMG$T = 


000001 


.IIF 


NE MMG*Tr MMGtT"! 




.IIF 


NIiF ERLtG, ERI.*G = 


000001 


.IIF 


NE ERLtG, ERLtG-=l 



If device time-out support is part of your system, the .DRDEF macro also 
issues the .MCALL statement for the .TIMIO and .CTIMIO macros: 



.IIF NE TIMtIT. .MCflLL. . T IHI r , C'T I M I 



The .DRDEF macro invokes tlie .QELDF macro to define queue element 
offsets and convenient symbols: 



000000 


.QELDF ' 




000000 


Q.LINK=0 




000002 


O.CSW=2, 




000004 


Q.EiLKN = 4. 




OOOOOA 


a.FUNC =6. 




000007 


0. JNUM=7. 




000007 


O.UNIT=7. 




000010 


Q.BUFF="010 




000012 


Q.WCirr="tJ12 




000014 


Q,C0«P="014 






. IRF' . X,<L):NK,CSW! 


. BLKN 




Q$'X=Q. 'X~4 






.ENIiR 




177774 


QtLINK = Q,LINK -4 




177776 


Q*CSU=Q.CSU-4 




000000 


Q*EiLKN = 0.EiLKN-4 




000002 


QtFUNC=--Q,FUN(>4 




000003 


QtJNUM^Q. JNUM -4 




000003 


Q*UNn=Q,UNi:T-4 




000004 


Q*EUFF = Q.. BUFF -4 




000006 


QtUCNT = Q.WCN"r-4 




000010 


QtCOMP^Q.COMP- 1 
.IF EQ MMGtT 
Q.ELGH=="016 

.IFF 




000016 


Q.PrtR^="016 




000012 


GtPAR^^-"rjl2 




000024 


«.ELGH = "0-::4 
.ENDC; 




000001 


HDERRt^l 




020000 


EOFt=20000 




002000 


SPFUNt--=2000 




004000 


HNDLRt=4000 




010000 


SPECLt=10000 




020000 


W0NLYt=200C0 




040000 


R0NLYt=40000 




100000 


FILSTt--lC0000 





- UNC , JNUM I UN I T . BUFF . WCNT . COMP!: 



The size of the device, its device-identifier byte, and its status word are 
defined: 



011300 RKriSIZ = 4800. 

000000 RKi|iCOD = 

100000 RKSTS = <0> KFILSTt:; 
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The default CSR and vector are defined: 



.IIF NDF RKtCSRr RKiCSP; = 177400 
.IIF NEIF RKJVECf RKtUEC = 220 
•GLOBL RKtCSRjRKtVEC 



The following direct assignment statements set up names for the device 
control registers. The register names, locations, and operation codes can be 
found in the PDP-11 Peripherals Handbook and in the hardware manual for 
the RK disk. 



7 


177400 


RKDS 


= 


RK*CSR 


8 


177402 


RKER 


= 


RKDS+2 


9 


177404 


RKCS 


= 


RKIiS + 4 


10 










U 


177406 


RKWC 


= 


RKriS + 6 


12 


177410 


RKBA 


= 


RKHS+IO 


13 


177412 


RKDA 


= 


RKDS+12 


14 











(DRIVE STATUS REGISTER 
JERROR REGISTER 
(CONTROL I STATUS 
(REGISTER 
JWORIi COUNT 

(BUS AIHiRESS 
(DISK ADDRESS 



The symbol RKCNT represents the number of times to retry an I/O transfer 
should an error occur. 



15 
lA 



000010 RKCNT = 10 



(NUMBER OF ERROR RETRYS 



The symbol RKNREG represents the number of device registers to record 
in the error log. 



17 
18 
19 



000007 RKNREG = 7 



(NUMBER OF REGISTERS TO 
(READ FOR ERROR LOG 



The following symbols define bits in the registers: 



20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
3 7 
38 

3 9 
40 
41 

4 2 
43 



( BITS IN DRIVE STATUS REGISTER (RKDS) 



160000 


DSID 


= 


160000 


010000 


DSDF'L 


:; 


10000 


004000 


DSRK05 


= 


4000 


002000 


DSDRU 


= 


2000 


001000 


DSSIN 


= 


1000 


000400 


DSSOK 


= 


400 


000200 


DSDRY 


== 


200 


000100 


DSREDY 


= 


100 


000040 


DSWPS 


= 


40 


000020 


DSSCOK 


= 


20 


000017 


DSSC 


= 


17 



BITS IN ERROR REGISTER (RKER) 



100000 


ERDRE 


= 100000 


040000 


ERCJVR 


= 40000 


020000 


ERUILO 


= 20000 


010000 


ERSKE 


■= 100 00 


004000 


ERPGE 


4000 



ilD OF INTERRUPTING 

(DRIVE (MASK) 

(DRIVE POWER LOU 

(SET => DRIVE IS RKOJi 

(DRIVE UNSAFE 

(SEEK INCOMPLETE 

(SECTOR COUNTER OK 

(DRIVE READY 

(READ/WRITE/SEEK READY 

(WRITE PROTECT STATUS 

(SECTOR COUNTER = SECTOR 

(ADDRESS 

(SECTOR COUNTER MASK 

((LOOK AHEAD) 



(DRIVE ERROR 

(OVERRUN 

(WRITE LOCK OUT VIOLATION 

(SEEK ERROR 

(PROGRAMMING ERROR 
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44 
45 
46 
47 
48 
49 
SO 
51 



S 
4 
5 
6 
7 

a 

9 
10 

11 

12 
13 
14 
15 
16 



002000 


ERNXM 


= 


S!000 


001000 


ERTiLT 


= 


1000 


000400 


ERTE 


= 


400 


000200 


ERNXIi 


= 


200 


000100 


ERNXC 


=:; 


100 


000040 


ERNXS 


a: 


40 


000002 


ERCSE 


= 


2 


000001 


ERWCK 


= 


1 




i BITS 


IN 


CONTROL 


100000 


CSERR 


= 


100000 


040000 


CSHE 


= 


40000 


020000 


CSSCP 


=: 


20000 


004000 


CSINHB 


= 


4000 


002000 


CSFMT 


= 


2000 


000400 


CSSSE 


= 


400 


000200 


CSRDY 


= 


200 


000100 


CSIE 


= 


100 


000060 


CSeA67 


= 


60 


000020 


CSBA16 


= 


20 


000016 


CSFUN 


= 


16 


000001 


CS60 


= 


1 



JNON-EXISTENT MEMORY 
fliATA LATE 
(TIMING ERROR 
fNON-EXISTENT 
(NON-EXISTENT 
JNON-EXISTENT 
(CHECKSUM ERROR 
(URITE CHECK ERROR 



DISK 

CYLINDER 

SECTOR 



AND STATUS REGISTER (RKCS) 



(ERROR 

5 HARD ERROR 

(SEARCH COMPLETE 

(INHIBIT BUS ADDRESS 

(INCREMENT 

(FORMAT 

(STOP ON SOFT ERROR 

(CONTROL READY 

(INTERRUPT ENABLE 

(BUS ADDRESS BITS 16-17 

(BUS ADDRESS BIT 16 

(FUNCTION CODE 

(GO BIT 



These are the operation codes: 



17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 



( FUNCTION CODES IN CSFUN 



000000 


FNRST 


S 


0*2 


000002 


FNURITE 


= 


1*2 


000004 


FNREAD 


= 


2*2 


000006 


FNMCHK 


= 


3*2 


000010 


FNSEEK 


= 


4*2 


000012 


FNRCHK 


=; 


5*2 


000014 


FNDRST 


a 


6*2 


000016 


FNWLK 


= 


7*2 




( BITS 


IN 


DISK A 


160000 


DAUNIT 


= 


160000 


017740 


DACYL 


s 


17740 


000020 


DASUR 


= 


20 


000017 


DASC 


= 


17 



(CONTROL RESET 

(URITE 

(READ 

(WRITE CHECK 

(SEEK 

(READ CHECK 

(DRIVE RESET 

(URITE LOCK 



(DRIVE SELECT BITS 
(CYLINDER BITS 
(SURFACE 
(SECTOR BITS 



Header Section 



•SBTTL DRIVER ENTRY 



The .DRBEG macro: 



3 000000 



.DRBEG RK 



The jfollowing lines are generated by the .DRBEG macro: 



000000 .A8ECT 

000052 . == 52 

.GLOBL RKENDfRKINT 

000052 000546 .UORD <RKEND-RKSTRT> 

.IF B <> 

000054 011300 .WORD RKDSIZE 
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, IFF 



.UORD 







.ENDC 










• IF B 


<> 




000056 


100000 


.IFF 
.ENDC 


.WORD 
.WORD 


RK3TS 


000060 


000007 
000176 


. = 176 


.WORD 


ERL*G + <MM6*T*2:: -KTIM«IT*4> 


000176 


177400 


.IIF DF 


RK»CSRf 


.WORD RK«CSR 


oooooo 




.fSECT 


RKDMR 




000000 




rkstrt: 

.IF NB 
.GLOBL 

.IFF 
.IF NB 


. WORD 

<> 


<-.>/2. -1 + "0100000 






.IIF NE 


83 
.WORD 


.ERROR iODD OR ILLEGAL VECTO 
S"C3 






.IFF 










.IF DF 


RK»VTB 








.GLOBL 


RK*yTB 
. WORD 


<RK$VTB-.>/2. -1 + "0100000 






.IFF 










.IIF NE 


RK*VECS2 


; .ERROR RK»UEC rODD OR ILLEGAL VECTOR 



The first word of the handler is RK$VEC: 



oooooo 000220 



■WORD RK»VECX"C3 



.ENDC 
.ENDC 
.ENDC 



The second word of the handler is the self-relative byte offset to the inter- 
rupt entry point RKINT. It is also used by the monitor abort I/O request 
code to find the abort entry point of the handler (it is the word immediately 
preceding the interrupt entry point). 

The third word of the handler contains the PS to be inserted into the device 
vector. The high byte must be 0. The low byte should be 340, for priority 7. 
If the low byte is lower than 340, the .FETCH code forces it to the actual 
new PS in the vector in order to specify priority 7. The condition bits can be 
used to distinguish up to 16 different interrupts or controllers. They are 
copied in to the PS word of the vector and set in the PS when the device in- 
terrupts using that vector. 



000002 000174 
000004 000340 
000006 



.WORD 



RKINT-. >"D340 



RKSYS; : 



The address of the fourth word of the handler, RKLQE, is placed in the 
monitor $ENTRY table. RKLQE points to the last queue element in the 
queue for this handler, thus making it easier for the monitor to add 
elements to the end of the queue. If there are no more elements in the queue, 
this word is 0. 



000006 OOOOOO RKLQE! 



.UORD 
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The fifth word or the handler, RKCQE, points to the third word, Q.BLKN, 
of the current queue element. li' there is no current queue element, RKCQE 
isO. 



000010 000000 RKCQE 1 



, UORD 



I/O Initiation Section 



The next statement is the first executable statement of the handler. This 
point is reached after a .READ or .WRITE programmed request is issued in 
a program. The monitor queue manager calls the handler with a JSR PC in- 
struction at the sixth word whenever a new queue element becomes the first 
element in the handler's queue. This situation occurs when an element is ad- 
ded to an empty queue, or when an element becomes first in the queue 
because a previous element was released. This section starts the I/O 
transfer. The I/O initiation code is executed at priority in system state. 
All r<3gisters are available to use in this section. At the end of the section, 
control is returned to the monitor with an RTS PC instruction. 

The MOV instruction sets the number of error retries to 8 and moves that 
value to RETRY. (The (PC) -I- notation points to RETRY.) At this point the 
handler has a brand new queue element and no retry is in progress. (If bit 15 
of the word at RETRY is 1, then a retry is in progress.) 



4 000012 012727 MOy 

000010 
5 

6 000016 000000 RETRY: .WORD 
7 



*RKCNT» <PC) + 



> INITIALIZE ERROR RETRY 

iCOUNT 

rSIGN BIT SET IF DRIVE 

fRESET IN PROGRESS 



RKCQE points to the block nuimber Q.BLKN in the queue element: 



8 


000020 


016705 
177764 


MOV 


RKCQE. R5 




(GET CURRENT QUEUE 


9 












fELEMENT POINTER 


10 


000024 


011502 


MOV 


eR5rR2 




(PICK UP BLOCK NUMBER 


11 


000026 


016504 
000002 


MOV 


QtUNIT-l(R5) 


.R4 


rCET REQUESTED UNIT 



(NUMBER IN HIGH BYTE 



The controller requires the unit number in the top three bits of the word 
loaded into RKDA: 



13 


000032 


006204 


ASR 


R4 


(SHIFT UNIT NUMBER 


14 


000034 


006204 


ASR 


R4 


( TO HIGH 3 BITS 


15 


000036 


006204 


ASR 


R4 


( OF LOU BYTE 


16 


000040 


000304 


SUAB 


R4 


(PUT UNIT NUMBER IN HIGH 


17 










(3 BITS OF WORD 


18 


000042 


042704 

017777 


BIC 


*-C<DAUNIT>.R4 


(ISOLATE UNIT IN DRIVE 


19 










(SELECT BITS 


20 
21 


000046 


000404 


BR 


2$ 


(ENTER COMPUTATION LOOP 
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The device unit and block number are known; the disk address for a read or 
write request must be calculated. Once determined, the disk address is 
stored in DISKAD in case it must be used again during a retry. The RK 
disk has 12 blocks per track, and two tracks per cyUnder. To find the disk 
address, the block number is divided by 12, and the quotient and remainder 
are separated. 



22 


000050 


060204 


It: 


A on 


R2.R4 


(ADD : 


16R TO ADDRESS 


23 


000052 


006202 




ASR 


R2 


I-R2 = 


3R 


24 


000054 


006202 




ASR 


R2 


!R2 = 


4R 


25 


000056 


060302 




ADD 


R3,R2 


!R2 = 


4R+S = NEW N 


26 


000060 


010203 


2»! 


MOV 


R2,R3 


(R3 = 


N = 16R+S 


27 


000062 


042703 
177760 




BIC 


♦"C<17>,R3 


jR3 = 


S 


28 


000066 


040302 




mc 


R3rR2 


iR2 = 


16R 


29 


000070 


001367 




BNE 


It 


JLOOP 


IF R <> 


30 


000072 


022703 
000014 




CMP 


♦12. ,R3 


JIF S 


< 12. 


31 


000076 


003002 




BGT 


3t 


) THEN F(S) = S 


32 


000100 


062703 




ADL'i 


*4fR3 


5 ELSE F(S)=F(12+S') 






000004 












33 












J 


16+S'=4+S 


34 


000104 


060304 


3*: 


ADD 


R3.R4 


JMERGE SECTOR INTO CYL 


35 












iTO GET DISK ADDRESS 


36 


000106 


010467 
000016 




Moy 


R4»riISKAri 


(SAVE 


IT 



The next statement points R5 to a queue element, since perhaps this is a 
retry and R5 is not already set up: 



37 ooou: 



016705 
177672 



AGAIN! MOV 



RKCQE.R5 



(POINT TO QUEUE ELEMENT 



This statement sets up the operation code for a write: 



38 000116 012703 
000103 
39 
40 000122 012704 

177412 
41 



MOV 



MOV 



*CSIE!FNlJRITE!CS60jR3 (ASSUME A WRITE 



♦RKDA.R4 



(FUNCTION 

(POINT TO DISK ADDRESS 

(REGISTER 



The disk address is saved in DISKAD. The significance of the bits in 
DISKAD, from high order to low order, is as follows: unit, cylinder, track, 
and sector. 



42 


000126 


012714 




MOV 


(PC) + ,(?R4 


(LOAD DISK ADDRESS X 


43 












(UNIT SELECT INTO RKDA 


44 


000130 


000000 


DISKAD! 


. WORD 





(SAVED COMPUTED DISK 


45 












(ADDRESS 


46 


000132 


022525 




CMP 


(R5>+» (R5)+ 


(ADVANCE TO BUFFER 


47 












(ADDRESS IN QUEUE ELT 



Much of the code in the handler is assembled based on the value of certain 
conditionals, such as MMG$T. The IF statement controls the assembly of 
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the code that follows. If the handler is assembled with MMG$T equal to 1, 
code following the .IFF statements is assembled. If the handler does not 
have extended memory support; enabled (that is, if MMG$T equals 0), code 
follov/ing the .IFT statements is assembled. Code following the .IFTF 
statements is always assembled, regardless of the value of MMG$T. 



46 
49 
50 
51 



, IF EQ MHG*T 
MOV 



,IFF 



(K-5) + .-(R4) 



iput buffer address into 
;rkea 



$MPPTR is a pointer to the monitor routine $MPPHY. This routine is 
available for NPR device handlers to use. It converts the virtual buffer ad- 
dress suppUed in the queue element into an 18-bit physical address that is 
returaed on the stack. The monitor supplies the virtual address in two 
words: Q.PAR and Q.BUFF. I'his form is used because it can be directly 
used by character-oriented (programmed transfer) devices. NPR devices 
such as the RK disk must convert this pair of words into an 18-bit physical 
addreiss consisting of a 16-bit low part and a two-bit extension. The extension 
bits £ire in positions 4 and 5 for use with UNIBUS controllers. The exten- 
sion bits must be ORed into the command word being built for RKCS. 



52 000134 004777 
000366 
53 

54 000140 012644 
55 
56 



JSR 



PC»e$MPPTR 



MOV <SP)+f-(R4) 
.ENDC iEO MHG*T 



fCONVERT USER VIRTUAL 

iAIiDRESS TO PHYSICAL 
>PUT LOU 16 BITS IN 
SRKEAf HIGH BITS ON STACK 



The next statement moves thei word count Q.WCNT from the queue ele- 
ment into RKWC, the device word count register. RT-11 can transfer up to 
32767 words per operation. However, it can never transfer an odd number 
of bytes. 



57 000142 012544 

58 000144 001407 



MOV 
BEQ 



(R5>+r-(R4) 
7» 



JPUT WORD COUNT INTO RKWC 
iO COUNT => SEEK 



The RK controller requires that all word counts be negative. 



59 


000146 


100403 


BMI 


5t 


(NEGATIVE => WRITEf 


60 










fSO ALL SET UP 


61 


000150 


005414 


NEQ 


eR4 


(POSITIVE => READr FIX 


62 










(COUNT FOR CONTROLLER 



The next statement sets up the operation code for a read: 



63 000152 012703 MOV 

000105 

64 000156 5t! 

65 .IF NE MM6»T 

66 000156 052603 BIS (SP)+rR3 
67 

68 .ENDC (NE MMG»T 

69 000160 010344 MOV R3.-<R4) 



*CSIE!FNREAD!CSG0>R3 (FUNCTION IS READ 



(MERGE HIGH ORDER ADDRESS 
(BITS INTO FUNCTION 



(START THE OPERATION 
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The next statement returns control to the monitor. The I/O transfer begins. 



70 000162 000207 6*i 
71 



RTS 



fC 



(AWAIT INTERRUPT 



The next statement sets up the operation code for a seek: 



72 000164 012744 7*t MOV 

000111 

73 .IF NE MM6«T 

74 000170 005726 TST (SF)+ 
75 

76 .ENDC JNE MHG»T 

77 000172 000773 BR 6* 



*CSIE!FNSEEK!CSG0,-(R4) fSTART UP A SEEK 



rliUMP THE HIGH ORDER 
(ADDRESS 



fAWAIT INTERRUPT 



Interrupt Service Section 



The following code is reached when an interrupt occurs: 



.SBTTL INTERRUPT ENTRY POINT 



The .DRAST macro: 



3 000174 .DRAST RK.5 

.GLOBL tlNPTR 
•IF B <> 
000174 000207 RTS X7 

.IFF 

BR 
.ENDC 



The abort entry point is the word preceding RKINT. Since no abort entry 
point was specified in the .DRAST macro, an RTS PC instruction was 
generated. 

At interrupt time, the new PC (RKINT) a^d new PS (340) are used. The 
handler calls the monitor through $INPTR in the handler to $INTEN in the 
monitor. The monitor switches to system state, lowers priority from 7 to 5, 
and calls the handler back. 



000176 004577 RKINT!! JSR 

000340 
000202 000100 .WORD 



•iSretlNPT'R 
"C<5«"040>X''0340 



The monitor calls the handler back at this point. Execution is now at priori- 
ty 5 and is in system state. The hardware has now finished the I/O opera- 
tion, and the handler must determine whether the transfer was successful 
or whether there was an error. 



4 000204 012705 
177402 
5 

6 000210 012504 
7 



MOM 



MOV 



*RKER,RJ 



<RS)+»R4 



iPOINT TO ERROR STATUS 

(REGISTER 

(GET ERROR REGISTER, 

(POINT TO RKCS 
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The value of RETRY is negati^'^e if a drive reset was just done. Bit 15 is the 
retry flag. 

8 000212 005767 TST RETRY (WERE WE DOING A DRIVE 

177600 

9 JREBET? 

10 000216 100013 BPL NORMAL JNO, NORMAL OPERATION 



Bit 15 of RKCS is the error summary bit. If there was an error during a 
drive reset, it is handled in the same way as an error that occurred during an 
I/O transfer. 



11 


000220 


005715 


TST 


BR5 


(ANY ERROR ON DRIVE 


12 










(RESET? 


13 


000222 


100411 


BMI 


NORMAL 


fYESr HANDLE NORMALLY 



R5 points to RKCS, the devices control and status register: 

14 000224 032715 BIT ♦CSSCPfBRS (RESET DONE YET (SEARCH 

020000 

15 (COMPLETE)? 



The RK device interrupts twice during a drive reset. The first interrupt 
should be ignored. 

16 000230 001472 BEQ RTSPC JNOj INTERRUPT AGAIN 

17 fUHEN RESET COMPLETE 



The .FORK macro causes the code that follows it to be executed at priority 
after all interrupts have been serviced, but before any jobs or their com- 
pletion routines execute. This sivoids executing lengthy code in the handler 
at high processor priority. 

18 000232 .FORK RKFBLK (CONTINUE RETRY AFTER 
000232 004577 JSR X5>etFKPTR 

000306 
000236 000240 .WORD RKFBLK - . 

19 (RESET AT FORK LEVEL 

20 000240 105067 RKRETRi CLRB RETRY+1 (CLEAR RESET-IN-PROGRESS 

177553 

21 (FLAG 

22 000244 000722 BR AGAIN (RETRY THE OPERATION (AT 

23 (FORK LEVEL) 
24 

25 000246 021527 NORMAL: CMP eR5 . tCSRDY ! CS IE ! FNSEEK (FIRST OF 2 

000310 

26 (INTERRUPTS CAUSED BY 

27 (SEEK? 



The RK device interrupts twice for a seek. The first interrupt should be ig- 
nored by the handler. The seelc is complete after the second interrupt has 
occurred. 



28 000252 001461 BEQ RTSPC (YESr IGNORE IT. 

29 (INTERRUPT AGAIN WHEN 

30 (COMPLETE 
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The next statement is reached when I/O is complete, or when there is an I/O 
error. The sign bit, bit 15, of RKCS is an error summary bit. If RKCS is 
negative, there was an error in the I/O transfer. 



31 000254 


005715 


TST 


PR 5 


32 000256 


100065 


BPL 


DONE 



!ANY ERRORS? 

(NO, WE'RE ALL DONE 



Errors axe processed at fork level, priority 0. 



33 000260 




.FORK 


RKFBLK 


(F-ROCE 


000260 


004577 
000260 


JSR 


Z5.etFKPTR 




000264 


000212 


.WURD 


RKFBLK - . 




34 








rLEWEL 



(PROCESS ERRORS AT FORK 



The following block of code is generated if the system supports error 
logging: 



,IF NE ERL*G 



R4 contains errors from RKER, the device error register. Unrecoverable 
errors that do not indicate hardware faults are not logged. 



36 000266 032704 
062340 
37 
38 000272 001027 



BIT 



BNE 



»ER0yR!ERUL0!ERNXMIERNXD!ERNXC!ERNXS,R4 



RKERR 



(USER ERROR? 

(YES, DON'T LOG IT 



Other types of errors are logged: 



39 


000274 


010705 


MOV 


F'CiRS 


40 










41 


000276 


062705 
000210 


ADD 


♦RKRBUF-. ,R5 


42 


000302 


010502 


MOV 


R5iR2 


43 










44 


000304 


012703 
177400 


MOV 


*RKtCSR,R3 


45 


000310 


012704 
000007 


MOV 


*RKNREG>R4 


46 










47 


000314 


012325 


RKRREG: MOV 


(R3)+r (R5)+ 


48 


000316 


005304 


DEC 


R4 


49 


000320 


001375 


BNE 


RKRREG 


50 


000322 


012703 
004007 


MOV 


♦RKNREG+<RKC 


51 










52 


000326 


016705 
177456 


MOV 


RKCQE,R5 


53 










54 


000332 


116704 
177460 


MOVE 


RETRY »R4 


55 










56 


000336 


005304 


DEC 


R4 


57 










58 


000340 


004777 
000172 


JSR 


PC,8*ELPTR 


59 


000344 


012705 
177402 


MOV 


*RKER,RS 


60 


000350 


012504 


MOV 


<R5)+fR4 


61 






.ENDC (NE ERL*G 





(GET REGISTER SAVE AREA 

( ADDRESS 

( IN A PIC WAY 

(SAVE ADDRESS IN FOR 

(ERROR LOGGER 

(POINT TO RK REGISTERS 

(GET COUNT OF REGISTERS 



(TO COPY 

(MOVE REGISTERS TO BUFFER 

(DONE? 

(NO, MORE 



(REGS/TOTAL RETRY COUNT 
(POINT TO THIRD WORD OF 



(CU)EUE ELEMENT 

(GET RK»COD(=0)/RETRY 



(COUNT 

(RETRY COUNT VALUE AFTER 
(IT IS DECREMENTED 
(CALL ERROR LOGGER 

(RESET REGISTERS 

( ON RETURN 
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63 


000356 


105715 3«: 


TSTB 


eR5 


64 


000360 


100376 


BPL 


3$ 


65 


000362 


105367 
177430 


DECB 


RETRY 


66 


000366 


001414 


BEQ 


HERRO 


67 


000370 


032704 
110000 


BIT 


*ERDR 



The next section of code retrujs both soft (such as checksum) and hard 
(hardware malfunction) errors. R5 points to RKCS. 

62 000352 012715 RKERR! MOV »FNRST ! CSBO j eR5 iRESET CONTROLLER 
000001 



When the controller is ready, it sets bit 7 of the low byte of RKCS. 

fUAIT 

i FOR RESET TO TAKE 

jANY RETRIES LEFT? 

!NOi CALL IT A HARD ERROR 
♦ERDRE!ERSKE>R4 JSEEK INCOMPLETE OR DRIVE 



Both seek incomplete and drive error require a drive reset before the opera- 
tion can be retried. 

68 rERROR? 



Common errors for which the I/O transfer should be retried are checksum 
errors, data late errors, and timing errors. 

69 000374 001721 BEQ RKRETR fNOf JUST RETRY OPERATION 



The next statement is reached if there is a seek incomplete or drive error 
condition. RKD A was cleared by the controller reset above, but the disk ad- 
dress is saved in DISKAD. 

70 000376 016737 MOV BISKAD r e*RKDA fYESi RESELECT DRIVE 

177526 
177412 



The flag in RETRY is set here so that on the next interrupt, the handler will 
know that a drive reset, and not an I/O transfer, was the last operation 
done. 

71 000404 052767 BIS #100000 r RETRY (SET RESET- IN-PROGRESS 

100000 
177404 

72 rFLAS 

73 000412 012715 MOV *CSIE ! FNDRST ! CSGO r (?R5 (START A DRIVE 

000115 

74 (RESET 



The next statement returns control to the monitor to wait for the drive 
reset or seek to finish. 

75 000416 000207 RTSPC: RTS PC iAWAIT INTERRUPT 

The next statement is reached when there has been an I/O error that has 
been retried and could not be corrected. 
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1 000420 



0I670S 
177364 



HERROR! MOV 



RKCQEfRS 



JHARD ERRORi POINT TO 
iQUEUE ELEMENT 



The handler reports the error to the user program by setting bit (the hard 
error bit) in the Channel Status Word. R5 points to Q.BLKN; R5, 
decremented by 2, points to the address of the CSW. 



3 000424 052755 BIS 

000001 
4 

5 .IF NE ERL$G 

6 000430 000411 BR 
7 



*HriERR*,e-(R5) iSET HARB ERROR STATUS 

>IN CHANNEL 
RKEXIT JEXIT AFTER ERROR 



The following section is reached after a successful transfer. Successful 
transfers are logged at fork level, priority 0. 



8 


000432 




done: 


.FORK 


RKFBLK 




000432 


004577 
000106 




JSR 


ZS.etFKF'TR 


9 
10 


000436 


000040 




. UORIi 


RKFBLK - . 


000440 


012704 




MOV 


(F'C) + fR4 


11 












12 


000442 
000443 


377 
000 




.BYTE 


377rRKtC0ri 


13 












14 


000444 


016705 
177340 




MOV 


RKCQE.R5 


15 












16 


000450 


004777 
000062 




JSR 


PC»e*ELPTR 


17 






.IFF 






18 






done: 






19 






.ENUC 






20 


000454 


005067 
177336 


RKEXIT! 


CLR 


RETRY 



JCALL ERROR LOG AT FORK 



fLEVEL FOR SUCCESS 
iSUCCESSr SET RK ID CODE 
JIN HIGH BYTEr 
! -1 IN LOU BYTE FOR 

(SUCESS 

fPOINT TO THIRD WORD OF 

tQUEUE ELEMENT 
(CALL ERROR LOGGER 



rCLEAR RETRY AND RESET 
(FLAGS 



I/O Ck>mpletion Section 



The .DRFIN macro: 

22 000460 



.DRFIN RK 



(EXIT TO COMPLETION 



The .DRFIN macro generates the following block of code. This section lets 
the monitor know that the I/O operation is complete so that the queue ele- 
ment can be returned to the available element list. Control returns to the 
monitor with the JMP instruction. The monitor alerts the program if it was 
waiting for this transfer to finish, or it runs the program's completion 
routine, if any. 







.GLOEL 


RKCQE 




000460 


010704 




MOV 


X7jX4 


000462 


062704 
177326 




ADD 


*RKCQE-.iX4 


000466 


013705 
000054 




MOV 


e*-054,X5 


000472 


000175 
000270 




JMP 


e-0270<5) 



A-14 Appendix 



24 


000476 
000500 
000502 
000504 


000000 
000000 
000000 
000000 


RKFBLKI 


: .WORD 


0l>0f OirO 


JFORK QUEUE BLOCK 


25 






.IF NE 


ERL»G 






26 


000506 




RKRBUF! 


.BLKW 


RKNRED 


JERROR LOG STORAGE FOR 


27 












fREQISTERS 


28 






.ENDC 









Primary Driver 



.SBTTL BOOTSTRAP DRIVER 



The .IDRBOT macro: 



3 000524 



.IiREOT RK.BOOTlfREAI) 



Termination Section 

The .DREND macro is generated by .DRBOT: 



000524 


.BRENti RK 


000524 


.PSECT RKIU'R 




.IIF NDF RK«ENDf RK*END 




.IF EO .-RKtEND 


000524 


RKtENII! : 




.IF NE MMG*T 



Since the handler is for a system device, .DRBOT invokes .DREND to 
allocate the following table of ptointers. The pointers are to routines in the 
Resident Monitor. Some of thei following pointers are optional, and their 
assembly depends on which system conditionals are defined. 



000524 


000000 


tRLPTRi 


.' .UIORD 





000526 


000000 


*MPPTR! 


! .WORD 





000530 


000000 


*gtbyt; 


5 .UORti 





000532 


000000 


tPTBYTl 


:: .WORD 





000534 


000000 


jptwrd; 

,ENDC 
.IF NE 


; .WORD 
ERL*6 





000536 


000000 


tELPTR! 
.ENUC 
.IF NE 


: .WORD 

tim»it 





000540 


000000 


tTIMXT! 
.ENUC 


;: .WORD 





000542 


000000 


«inptr: 


: .WORD 





000544 


000000 


«fkptr: 

.GLOBL 


: .UORD 
RKSTRT 






The following line marks the end of the loadable portion of the handler. It is 
used to determine the handler's length. 



000546' 


RKEND == 
.ENDC 






.IIF NDF TPS, 


TPS=177564 




.IIF NDF TPEi 


TPB=177566 


000012 


LF = 12 




000015 


CR=15 
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001000 


B$BOOT= 


= 1000 










004716 


B«DEVN= 


=4716 










004722 


B»DEVU= 


= 4722 










004730 


B*READ= 
.IF EO 
B$DNAM= 
.IFF 


= 4730 

MMG«T 
= -'RRK 










071120 


6$DNAM= 
.ENDC 


'"RRKX 








000200 


000062 


.ASECT 
.=62 










000062 


000000' 




.UORIl 


RKBOOT jRKBEND- 


-RKBOOT. READ-RKBOOT 




000064 


001000 






i 






000066 


000210 












000000 




.PSECT 


RKBOOT 








000000 


000240 


ftKBOOT! 


; !NOP 






4 
5 


000002 


000416 




BR 


BOOTl 






000040' 


. 


= RKBOOTMO 


!PUT THE JUMP BOOT INTO 


6 












iSYSCOM AREA 


7 


000040 


000137 


BOOTl! 


JMP 


e*BOOT-RKBOOT 


SSTART THE BOOTSTRAP 


8 
9 




000574 












000210' 


, 


= RKBOOT+210 




10 


000210 


012703 


read: 


MOV 


*12.jR3 {PHYSICAL BLOCK TO RK 






000014 










11 












flilSK ADDRESS 


12 


000214 


000402 




BR 


2$ 


JENTER BLOCK NUMBER 


13 












{COMPUTATION 


14 














15 


000216 


062703 
000020 


i*i 


Aim 


♦20. R3 


{CONVERT DISK ADDRESS 


16 


000222 


162700 
000014 


2«: 


SUB 


♦12. tRO 




17 


000226 


100373 




BPL 


1» 




18 


000230 


060300 




ADD 


R3»R0 


{RO HAS DISK ADDRESS 


19 


000232 


012703 
177412 




HOV 


♦RKDA.R3 


{POINT TO HARDWARE DISK 


20 












{ADDRESS REGISTER 


21 


000236 


042713 




BIC 


♦"C<DAUNIT>.eR3 (LEAVE THE UNIT NUMBER 






017777 










22 


000242 


050013 




BIS 


RO.eRS 


{PUT DISK ADDRESS INTO 


23 












{CONTROLLER 


24 


000244 


010243 




MOV 


R2.-(R3) 


{BUFFER ADDRESS 


25 


000246 


010143 




MOV 


R1.-(R3) 


{WORD COUNT 


26 


000250 


005413 




NEG 


eR3 


{(NEGATIVE) 


27 


000252 


012743 
000005 




MOV 


♦FNREAD!CSGO»- 


■(R3) {START DISK READ 


28 


000256 


105713 


3*: 


TSTB 


(?R3 


{WAIT UNTIL COMPLETE 


29 


000260 


100376 




BPL 


3* 




30 


000262 


005713 




TST 


eR3 


(ANY ERRORS 


31 


000264 


100577 




BMI 


BIOERR 


{HARD HALT ON ERROR 


32 








fCLC 




{CARRY IS CLEAR FROM 


33 












{'TST' ABOVE 


34 
35 
36 


000266 


000207 




RTS 


PC 






000574' 


^ 


= RKBOOT+574 




37 


000574 


012706 
010000 


BOOT! 


MOV 


♦lOOOO.SP 


{SET STACK POINTER 


38 


000600 


013746 
177412 




MOV 


8+RKDA.-(SP) 


{GET THE RK UNIT NUMBER 


39 


000604 


006116 




ROL 


esp 


{SHIFT IT 


40 


000606 


006116 




ROL 


esp 


( AROUND THE TOP 


41 


000610 


006116 




ROL 


esp 


( TO THE LOU 3 BITS 


42 


000612 


006116 




ROL 


esp 


{ OF THE WORD 


43 


000614 


042716 
177770 




BIC 


♦"C<7>.BSP 


{EXTRACT THE UNIT NUMBER 


44 


000620 


012700 
000002 




MOV 


♦ 2>R0 


(READ IN SECOND PART OF 


45 












(BOOT FROM BLOCK 2 


46 


000624 


012701 
002000 




MOV 


♦<4*400>.R1 


(EVERY BLOCK BUT THE ONE 


47 












(WE ARE IN <4 BLOCKS) 


48 


000630 


012702 
001000 




MOV 


♦1000»R2 


(INTO LOCATION 1000 


49 


000634 


004767 
177350 




JSR 


PC. READ 


(GO READ IT IN 
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so 000640 



51 
32 
53 000646 



54 000654 

55 000660 

56 

57 000664 
000546 



000664 



000664 
000670 



012737 
000210 
004730 



012737 
071120 
004716 
012637 
004722 
000137 
001000 



MOM »REAIi-R;KBOOT.e*BtREAD J STORE START 



iLOCATION FOR READ 
^ROUTINE 
HOl^ *B*DNAMretEi$IiEVN fSTORE RAD50 DEVICE NAME 



MOV <SF') + .e*B»DEVU (STORE THE UNIT NUMBER 
JMP B»B»BOOT JSTART SECONDARY BOOT 



.DREMD RK 
.PSECT RKDVR 
.IIF NDF RK«END» RK*END.' 
.IF EQ .-RKtEND 
RK'*ENDi : 

.if ne mmg»t 
«rlptr;: .word 
smpptr!; .word 
♦gtbyts: .word 

.WORD 



♦PTBYT! : 

»ptwrd:! .word 

.ENDC 

.IF NE ERLtG 

$elptr;! .word o 

.ENDC 

.IF NE TIM«IT 

*timit;: .word o 

.ENDC 

»inptr.': .word o 

»FKPTR!t .WORD 

.GLOBL RKSTRT 

RKEND == . 

.IFF 

.PSECT RKBOOT 

.IIF LT <RKBC)0T-.+664>f .ERROR JPRIMARY BOOT TOO LARGE 

000664' . = RKIiOOT+664 
004167 bioerr; JSR R1»REP0RT 

000002 

000766 .WORD lOERR-RKBOOT 



The following routine is entered when an error occurs. It prints the fatal 
part of the message, followed by the message text, a carriage return, and 
two line feeds. 



000672 


012700 REPORT! MOV 


♦ BOOTF-RI 




000746 






000676 


004167 
000030 


JSR 


R1»REP 


000702 


012100 


MOV 


(R1>+»R0 


000704 


004167 
000022 


JSR 


R1,REP 


000710 


012700 
000762 


MOV 


♦ CRLFLF-i 


000714 


004167 
000012 


JSR 


R1,REP 


000720 


000005 


RESET 




000722 


000000 


HALT 




000724 


000776 


BR 


.-2 



The following routine prints the error message: 



000726 112037 REPOR ! MOVB <RO)+>B»TPB 

177566 
000732 105737 REP i TSTB OtTPS 

177564 
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000736 
000740 
000742 
000744 


100375 
105710 
001371 
000201 




000746 
000762 
000766 


015 
015 
111 




001000 




58 
59 




000001 



BPL REP 

TSTB eRO 

BNE REPOR 

RTS Rl 

BOOTF: .ASCIZ <CR><LF>"?EiOOT-U-'<200> 
CRLFLF: .ASCIZ <cr><lf><lf> 

ioerr; .ASCIZ "I/O error* 

.EVEN 
RKBEND! ! 
.ENDt; 

.END 



The symbol table is generated at the end of the assembly listing: 



SYMBOL TABLE 



AGAIN 


000112R 


002 


ERNXM = 


002000 


REPORT 


000672R 


003 


BIOERR 


000664R 


003 


ERNXS = 


000040 


RETRY 


000016R 


002 


BOOT 


000574R 


003 


EROVR = 


040000 


RKBA = 


177410 




BOOTF 


000746R 


003 


ERPGE = 


004000 


RKBEND 


OOIOOORG 


003 


BOOTl 


000040R 


003 


ERSKE = 


010000 


RKBOOT 


O0OOO0R6 


003 


B*BOOT= 


001000 




ERTE = 


000400 


RKCNT = 


000010 




B$DEVN= 


004716 




ERUCK = 


000001 


RKCQE 


OOOOIORG 


002 


B$DEUU= 


004722 




ERULO = 


020000 


RKCS = 


177404 




B«DNAH^ 


071120 




FILST*= 


100000 


RKDA = 


177412 




B«READ= 


004730 




FNDRST= 


000014 


RKDS = 


177400 




CR 


000015 




FNRCHK= 


000012 


RKDSIZ= 


011300 




CRLFLF 


000762R 


003 


FNREAD= 


000004 


RKENB = 


000546Re 


002 


CSBA16= 


000020 




FNRST = 


000000 


RKER = 


177402 




CSBA67= 


000060 




FNSEEK= 


000010 


RKERR 


000352R 


002 


CSERR = 


100000 




FNWCHK= 


000006 


RKEXIT 


000454R 


002 


CSFMT = 


002000 




FNULK = 


000016 


RKFBLK 


000476R 


002 


CSFUN = 


000016 




FNWRIT= 


000002 


RKINT 


000176RG 


002 


CSGO = 


000001 




HnERR*= 


000001 


RKLQE 


000006RG 


002 


CSHE = 


040000 




HERROR 


000420R 


002 RKNREG= 


000007 




CSIE = 


000100 




HNDLR»= 


004000 


RKRBIJF 


000506R 


002 


CSINHB= 


004000 




IOERR 


000766R 


003 RKRETR 


000240R 


002 


CSRDY = 


000200 




LF 


000012 


RKRRE6 


000314R 


002 


CSSCP = 


020000 




hMG»T = 


000001 


RKSTRT 


OOOOOORG 


002 


CSSSE = 


000400 




NORMAL 


000246R 


002 RKSTS = 


100000 




DACYL = 


017740 




Q»BLKN= 


000000 


RKSYS 


000006RG 


002 


DASC = 


000017 




Q$BUFF= 


000004 


RKWC = 


177406 




DASUR = 


000020 




Q*COMP= 


000010 


RKtCOD= 


000000 




DAUNIT= 


160000 




QtCSW = 


177776 


RK«CSR= 


177400 G 




DISKAD 


000130R 


002 


Q*FUNC= 


000002 


RK*END 


000524RG 


002 


DONE 


000432R 


002 


Q$JNUM= 


000003 


RK»VEC= 


000220 G 




DSriPL = 


010000 




Q*LINK= 


177774 


RONLY«= 


040000 




nSDRU = 


002000 




QtPAR = 


000012 


RTSPC 


000416R 


002 


BSDRY = 


000200 




0«UNIT= 


000003 


SPECL*= 


010000 




DSID = 


160000 




Q*UCNT= 


000006 


SPFUN$= 


002000 




tiSREtiY = 


000100 




Q.BLKN= 


000004 


TIM»IT= 


000001 




DSRK05= 


004000 




Q.BUFF= 


000010 


TPB 


177566 




nssc = 


000017 




Q.COMP= 


000014 


TPS 


177564 




DSSCOK= 


000020 




Q.CSW = 


000002 


WONLY»= 


020000 




DSSIN =•■ 


001000 




Q.ELGH= 


000024 


♦ELPTR 


000536RG 


002 


DSSOK = 


000400 




Q.FUNC.-= 


000006 


»FKPTR 


000544RG 


002 


DSUPS = 


000040 




Q.JNUM= 


000007 


»GTBYT 


000530R6 


002 


EOF» = 


020000 




Q,LINK= 


000000 


tINPTR 


000542RG 


002 


ERCSE = 


000002 




O.PAR = 


000016 


♦MPPTR 


000526RG 


002 


ERDLT = 


001000 




Q.UNIT= 


000007 


$PTBYT 


000532RG 


002 


ERDRE = 


100000 




G.WCNT= 


000012 


fPTWRD 


000534RG 


002 


ERL*6 = 


000001 




READ 


000210R 


003 tRLPTR 


000524R6 


002 


ERNXC = 


000100 




REP 


000732R 


003 «TI«IT 


000540RG 


002 


ERNXI.I = 


000200 




REPOR 


000726R 


003 






. ABS. 


000200 
000000 


000 
001 












RKDVR 


000546 


002 












RKBOOT 


001000 


003 













ERRORS detected; 

VIRTUAL MEMORY USED; 10240 WORDS ( 39 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 73 PAGES 
rRK/LJME/L;TTM=CND»RK 
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Figures A-2: DX Diskette Handler 

DX VOt.Ol MACRO V04.00 17-C»CT-79 23,:30:i2 
TABLE OF CONTENTS 



3-- 
7- 
8- 
10- 
14- 
15- 
16- 



3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 



MACROS AND DEFINITIONS 

INSTALLATION CHECKS 

DRIVER REUUEST ENTRY POINT 

START TRANSFER OR RETRY 

SILOFE - FILL OR EMPTY THE SILO 

TABLES, FORK BLOCK, END OF DRIVER 

BOOTSTRAP DRIVER 

{CONDITIONAL FILE FOR HANDLER EXAMPLES 

r 

{CND.MAC 

r 

f9/4/79 JDC 

(ASSEMBLE WITH HANDLER .MAC FILE TO ENABLE 
;i8-BIT I/O, TIME-OUT, AND ERROR LOGGING 
(FOR HANDLER. 



J18-BIT I/O 
JERROR LOGGING 
iTIME-OUT 



000001 


MMG$T 


= 1 


000001 


ERLtG 


= 1 


000001 


TIM»IT 


= 1 



3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 



TITLE DX V04.01 
IDENT /V04.C)1/ 
RT-11 RXOl DISK HANDLER 

COPYRIGHT (C) 1979 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE 
USED AND COPIED ONLY IN ACCORDANCE WITH -THE 
TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF 
THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY 
OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND 
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE 
WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS 
A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR 
RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT 
SUPPLIED BY DIGITAL. 



Preamble Section 



.SBTTL MACROS AND DEFINITIONS 
.MCALL .DRDEF 



The following two macros are; used for consistency checks within the 
handler. They generate P errors at assembly time when inconsistencies exist. 



6 

7 

8 

9 

10 

11 

12 

13 

14 

15 



MACRO 


.ASSUME A1,CND,A2 


IF 


CND <A1>-<A2> 


IFF 




ERROR 


)"A1 CND A2' IS NOT TRUE 


ENDC 




ENDM 


.ASSUME 


MACRO 


,BR TO 


IF DF 


TO 


IF NE 


.-<T0> 


ERROR 


(NOT AT LOCATION 'TO" 
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16 
17 
18 



.ENDC 
.EN DC 
.ENDM .BR 



The .DRDEF macro: 



1 000000 .DRDEF DX r 22,F ILST* ! SPFUNt t 756» 1 77170f 261 

.MCALL .DRASTf .DRBEG, .DRBOTi .DREND, .DRFIN, .DRSET 

.MCALL .DRVTBf .FORKf .QELDF 

.IIF NDF TIM*rT, TIMtIT=0 
000001 .IIF NE TIMtn» TIMtIT=l 

•IIF NDF MM6»T. MMGtT^O 
000001 .IIF NE HM6»Tf MhGtT=l 

.IIF NDF ERL»G» ERL*G=0 

000001 .IIF NE ERL*B» ERL«6=1 

.IIF NE TIh»IT, .MCALL . TIMIO , , CTIM I 
000000 .QELDF 

000000 Q.LINK=0 

000002 Q.CSU=2. 
000004 CJ.BLKN = 4. 

000006 Q.FUNC=6. 

000007 Q.JNUh=7. 
000007 Q.UNir=7. 
000010 Q.BUFF="010 
000012 Q.UCNT=="01;5 
000014 O-COhPs-Oll 

.IRP X. a.INK,i:;BWfRLKN>FUNC> JNUh.UNIT,BUFFfWCNTFCOMP> 

Q*'X=Q, 'X-4 

.ENDR 
177774 Q$LINK = Q.LINK -4 
177776 Q»CSW=Q.CSW-4 

000000 QtBLKN=Q.BLKN--4 

000002 Q$FUNC=Q.FUNC -4 

000003 C1$JNUM = Q. JNUM-4 

000003 Q*UNIT=Q.UNIT-4 

000004 Q»BUFF=Q-BUFF-4 
000006 (J*WCNT = Q.WCNT ■ i 
000010 Q*C0MP = C1,C0MP- 4 

. IF EQ MMGt.T 

Q.ELGH==' Olii 

.IFF 
000016 Q.PAR="D16 
000012 QtPAR="012 
000024 Q.ELGH-="C)24 

.ENDC 

000001 HD£RR»=1 
020000 E0F»=20000 
002000 SPFUN*=2000 
004000 HNDLR»=4000 
010000 SPECLt=10000 
020000 W0NLY»=20000 
040000 RONLY*=40000 
100000 FILST»=100000 
000756 DXDSIZ=756 
000022 DX*C0D-22 

102022 DXSTS=<22> ! <FILST* ! SPFUN*> 

.IIF NDF DXtCSRp DX*CSR~177170 
.IIF NDF DX»MECf DX*VEC=264 
.GLOBL DXJCSR.DXtVEC 



If DXT$0 = 1, there are two controllers: 



3 

4 

5 

6 

7 

8 

9 

10 

11 

12 



.IIF NDF I:iXT»Of DX1*0 = 

i ERROR LOG l.>ALUES 
000003 DXNREG = 3 



000010 RETRY 



8. 



(DEFAULT TO ONLY ONE 
! CONTROLLER 



»♦ OF REGISTERS TO READ 
(FOR ERROR LOG. 



JRETRY COUNT 
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An internal flag for special functions: 



13 
14 
15 
16 



3 
4 
3 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
li^ 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 



100000 SPFUNC 



100000 



JSFECIAL FUNCTIONS FLAG 
;iN COMMAND WORD 



000044 



JSW = 44 

i RXOl C0NTR(5LLER DEFAULTS 

.IIF NDF T)X$WC2f DX$VC2 == 270 

,IIF NDF DX»CS2» riXtCS2 == 177174 



iJOB STATUS WORD 



(2ND CONTROLLER 

J VECTOR 

S2ND CONTROLLER 

fCSR 



; CONTROL AN[i STATUS REGISTER BIT DEFINITIONS 



(INITIATE FUNCTION 
MJNIT BIT 
(DONE BIT 
JINTERUFT ENABLE 
(TRANSFER REOUEST 
(CONTROLLER IS RX02 
((ALUAYS 0) 
(RXll INITIALIZE 
(ERROR 



( CSR FUNCTION CODES IN BITS 1-3 



000001 


CS60 


= 


1 


000020 


CSUNIT 


= 


20 


000040 


CSDONE 


= 


40 


000100 


CSINT 


= 


100 


000200 


CSTR 


= 


200 


004000 


CSRX02 


= 


4000 


040000 


CSINIT 


= 


40000 


100000 


CSERR 


= 


loaooo 



000000 


CSFBUF 


- 


0*2 


000002 


CSEBUF 


= 


1*2 


000004 


CSURT 


= 


2*2 


000006 


CSRD 


= 


3*2 


000012 


CSRDST 


= 


5*3 


000014 


CSURTD 


=; 


6*2 


000016 


CSMAIN 


= 


7*2 



(0 - FILL SILO 

( (PRE-WRITE) 

(1 - EMPTY SILO 

( (POST-READ) 

(2 - WRITE SECTOR 

(3 - READ SECTOR 

(4 - UNUSED 

(5 - READ STATUS 

(6 - WRITE SECTOR WITH 

(DELETED DATA 

(7 - MAINTENANCE 



Intei-nal consistency checks: 



34 000000 



35 
36 



37 
38 



39 



3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 



000000 



000000 



000001 
000002 
000004 
000100 
000200 



.ASSUME CSRD82 

.IF NE 

. IFF 

, t:RROR ( ■CSRD82 NE 

.ENDC 



NE 
CSRDX2>-<0> 



BIT MUST BE ON 



IS NOT true: 



(IN READ 

(2 BIT MUST BE OFF 



.ASSUME CSWRT82 EQ 

•IF EO <CSURTS2>-<0> 

. IFF 

.ERROR ("CSI.)RTS2 EO 0' IS NOT TRUE 

.ENDC 

(IN WRITE 
.ASSUME CSURTDX2 EO (2 BIT MUST BE OFF 

.IF EQ <CSURTDS2>-<0> 
.IFF 

.ERROR (•CSIJRTD82 EO 0' IS NOT TRUE 
.ENDC 

(IN WRITE 

( ERROR AND STATUS REGISTER BIT DEFINITIONS 
= . 1 



ESCRC 

ESPAR 

ESID 

ESDD 

ESDRY 



4 
100 
200 



fCRC ERROR 
(PARITY ERROR 
(INITIALIZE DONE 
(DELETED DATA MARK 
(DRIVE READY 



i MISCELLANEOUS HARDWARE DEFINITIONS 



172342 KISARl 



172342 



(KT-11 PAR FOR MAPPING 
(USER BUFFER 
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14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 



GENERAL COMMENTS! 

THIS HANDLER SERVES AS THE STANHARH RT-11 RXOl DEVICE 
HANDLER AS BOTH THE SYSTEM DEVICE HANDLER AND NON- 
SYSTEM HANDLER. IT ALSO PROVIDES THREE SPECIAL 
FUNCTION CAPABILITIES TO SUPPORT PHYSICAL I/O ON THE 
FLOPPY AS A FOREIGN VOLUME. THE SPECIAL FUNCTIONS ARE; 

CODE ACTION 

377 ABSOLUTE SECTOR READ. 

WCNT=TRACKf BLK=SECTOR» BUFFER=65-U0RD 

BUFFER OF WHICH WORD 1 IS DELETED 

DATA FLAG. 
376 ABSOLUTE SECTOR WRITE. ARGUMENTS SAME 

AS READ. 
375 ABSOLUTE SECTOR WRITE WITH DELETED DATA. 

1ST WORD OF 65-WORD BUFFER ALWAYS SET 

TO 0. 

IN STANDARD RT-11 MODE A 2:i INTERLEAVE IS USED ON A 
SINGLE TRACK AND A 6 SECTOR SKEW IS USED ACROSS TRACKS. 
TRACK IS LEFT ALONE FOR PROPOSED ANSI COMPATABILITY . 



Installation checks: 



.SBTTL INSTALLATION CHECKS 



3 
4 
5 


000000 




.ASECT 










000200 


^ 


= 200 




ilNSTALLATION CHECK GOES 


6 
7 
8 












J HERE 


000200 


000240 




NOP 




iSAME CHECK FOR SYSTEM 


9 












(AND NON-SYSTEM HANDLER 


10 


000202 


032777 
004000 
177766 




BIT 


*CSRX02,ei76 


;IS THE RX02 BIT ON? 


11 


000210 


001001 




6NE 


It 


iYES> THIS ISN'T AN RXOl 


12 












(SO DON'T INSTALL IT 


13 


000212 


005727 




TST 


(PC) + 


!N0> INSTALL RXOl BY 


14 












iCLEARING C BIT 


15 


000214 


000261 


1$: 


SEC 




JSET CARRY TO NOT 


16 












(INSTALL DY 


17 


000216 


000207 




RTS 


PC 





Header Section 



.SBTTL DRIVER REBUEST ENTRY POINT 
.ENABL LSB 



The .DRBEG macro: 



5 000220 






.DRBEG 


DX 


000220 


000052 


.ASECT 
. = 52 










.6L0BL 


DXENDi 


DXINT 


000052 


001142 


.IF E 


.WORD 

<> 


<DXEND-DXSTRT 


000054 


000756 


.IFF 

.ENDC 
.IF B 


.WORD 
.WORD 

<> 


DXDSIZE 


000056 


102022 


.IFF 
.ENDC 


.WORD 
.WORD 


DXSTS 
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000060 


000007 
000176 


. = 176 


.WORD 


ERL»G+<h 


1MG*T*2>+<TIM»IT«4> 


000176 


177170 


.IIF IiF 


VX*CSRf 


• WORD 


DXtCSR 


000000 




.PSECT 


DXDVR 






000000 




nXSTRT!: 
.IK Nil 
.GLOEU. 














.WORD 


<-.>/2. 


-1 + "0100000 






.IFF 












.IF NB 


<> 










• IIF m 


X3 
.WORD 


.ERROR 
X"C3 


;ODD OR ILLEGAL VECTOR 






.IFF 












.IF IiF 


IiXtVTB 










.GLOBL 


DXtVTB 












.WORD 


<DX*VTB- 


-,>/2. -1 + "0100000 






• IFF 












.IIF ne: 


DXtMECS3 .ERROR 


DXtVEC fODD OR ILLEGAL VECTOR 


000000 


000264 


.ENDC 
.ENDC 
.ENDC 


.WORD 


DX*yEC8' 


'C3 


000002 


000414 




.WORD 


DXINT-. 


i"0340 


000004 


000340 










000006 




DXSYs: : 








000006 


000000 


dxlqe: : 


.WORD 







000010 


000000 


dxcqe: : 


.WORD 








I/O Initiation Section 



6 000012 012727 MOV 

000010 

7 000016 000000 rxtry; .word 



* RETRY > (FX) + 



S INITIALIZE RETRY COUNT 
! i RETRY COUNT 



The following instructions assemble the controller function to start up an 
operation, and sort out special functions. 



(3 000020 



10 000024 

11 000026 

12 

13 000032 

14 

15 000034 

16 000036 
17 

IB 000040 

IV 000042 



21 000046 

23 000046 

24 000052 
25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 000054 

37 



016703 
177764 

012305 
012704 
000007 

112301 

112300 
106200 

103002 
052704 
000020 



132700 
000003 
001153 



It! 
.IF EO 



.IFF 



MOV 



MOV 
MOV 



MOVB 



MOVE 

ASRB 



BCC 
BIS 



DXT«0 
BITB 

BNE 

MOV 

ASfJB 

BCC 
MOV 



DXCQE. R3 



(R3)+fR5 
*CSRD!CS60,R4 



(R3)+fRl 



(R3)+.R0 
RO 



1$ 
*CSUNITtR4 



>GET POINTER TO QUEUE 

JELEMENT 

fGET BLOCK NUMBER 

rCUESS THAT CONTROLLER 

(FUNCTION IS READ 

(PICK UP SPECIAL FUNCTION 

(CODE (SIGN EXTENDED) 

(PICK UP THE UNIT NUMBER 

(SHIFT IT TO CHECK FOR 

(ODD UNIT 

(BRANCH IF EVEN UNIT 

(SELECT ODD UNIT FOR 

(TRANSFER 



(ONE CONTROLLER 
♦6/2 rRO 

RXERR 

♦DXtCSR. RXCSA 

RO 

2t 
♦DX»CS2.RXCSA 



012300 



3t: ASRB RO 

BCS RXERR 

,ENDC JEQ DXTtO 

MOV (R3)+.R0 



(ANY UNITS BUT OR 1? 

(BRANCH IF YES. ERROR 

(ASSUME FIRST DX 

(CONTROLLER 

(SHIFT UNIT TO CHECK FOR 

(SECOND CONTROLLER 

(NOPE. FIRST CONTROLLER 

(CHANGE CSR TO USE 

(SECOND CONTROLLER 

(BUT WAS IT UNIT 4 TO 7? 

(ERROR IF SO 

(GET THE USER'S BUFFER 
(ADDRESS 
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38 000056 012302 

39 000060 100002 
40 

41 000062 124444 
42 



HOy (R3)+fR2 
BPL 3» 



CMPB 



-(ft4) r-(R4) 



SGET WORD COUNT 
SPOSITIVE MEANS READ. 
iSO ALL SET UP 
^CHANGE CSRD (3*2) TO 
JCSWRT (2*2) FOR WRITE 



Ensure that a write equals a read code minus 2: 



43 


000064 




.ASSUME 


CSURT 


EO CSRD-2 








• IF 


EQ 


<CSWRT>-<CSRri-2> 








• IFF 












•ERROR 


i 'CSURT 


EQ CSRII-2' IS NO 








.ENDC 






44 


000064 


005402 




NEC 


R2 


45 












46 


000066 


006301 


3«! 


ASL 


Rl 


47 












48 


000070 


060701 




ADD 


PC.Rl 


49 













SAND MAKE WORD COUNT 

fPOSITIVE 

(DOUBLE THE SPECIAL 

JFUNCTION CODE 

(FORM PIC REFERENCE 

(TO CHGTBL 



The codes for read and write operations stay the same. If the operation is 
for a special function, this routine sets the sign bit of the function code 
word, and modifies the function: 



50 000072 

51 

52 000076 

53 

54 000102 

55 

1 
3 



066104 
001006 



010467 
000332 



100435 



ADD 



MOV 



BMI 



CHGTBL-. (R1),R4 (MODIFY THE CODE f SET 
R4.RXFUN2 



(SIGN BIT IF SPFUN 
(SAVE THE FUNCTION CODE 



7t 



(AND SPFUN FLAG 

(IF SPFUN, GO DO SPECIAL 

(SETUP 



( NORMAL I/Ot CONVERT TO TRACK AND SECTOR NUMBER 
( AND INTERLEAVE 



FILLCT indicates whether a multiple of four sectors has been written. If 
not, the handler will later zero-fill to reach a multiple of four. 



4 000104 


110267 


MOVB 


R2fFILLCT 


3 

6 000110 


000507 






105367 


DECB 


FILLCT 




000503 






7 000114 

8 

9 000116 


006302 


ASL 


R2 


006305 


ASL 


R5 


10 








11 000120 


006305 


ASL 


R5 


12 000122 


012704 


MGV 


<PC)+>R4 


13 








14 000124 


371 


.BYTE 


-7,-26. 


000125 
15 
16 000126 


346 






022705 4t; 


CMP 


*26.*200,R5 




006400 






17 000132 


101002 


BHI 


5t 


18 000134 


062705 
171400 


ADIr 


»-26.*200,R5 


19 








20 000140 

21 

22 000142 


006105 5f: 


ROL 


R5 


105204 


INCB 


R4 


23 000144 


003770 


BLE 


4f 


24 000146 


110501 


MOVB 


R5,R1 


25 









(SAVE WORD COUNT IN CASE 

(WE HAVE TO FILL 
(EXTRA SECTORS ON WRITE 

(MAKE WORD COUNT UNSIGNED 

(BYTE COUNT 

(NORMAL READ/WRITE. COM- 

(PUTE REAL SECTOR NUMBER 

(AS BL0CK*4 

(LOOP COUNT FOR 8 BIT 

(DIVISION 

(COUNT BECOMES 1, -26 IN 

(HIGH BYTE FOR LATER 

(DOES 26 GO INTO DIVIDEND? 

(BRANCH IF NOT, C CLEAR 
(SUBTRACT 26 FROM 

(DIVIDEND, SET C 

(SHIFT DIVIDEND AND 

(QUOTIENT 

(DECREMENT LOOP COUNT 

(BRANCH UNTIL DIVIDE DONE 

(COPY TRACK NUMBER 0!75» 

(ZERO EXTEND 
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26 


000150 


060405 




ADD 


R4>R5 




JBUMP TRACK TO 1-76, 


27 














(MAKE SECTOR<0 


28 


000152 


010104 




MOV 


R1>R4 




rCOPY TRACK NUMBER 


29 


000154 


006301 




ASL 


Rl 




SMULTIPLY 


30 


000156 


060401 




ADD 


R4>R1 




! BY 


31 


000160 


006301 




ASL 


Rl 




; 6 


32 


000162 


162701 


6»J 


SUB 


#26.>R1 (REDUCE 


TRACK NUMBER * 6 






000032 












33 














; MOD 26 


34 


000166 


003375 




BGT 


6* 




} TO FIND OFFSET FOR 


35 














F THIS TRACKr -26!0 


36 


000170 


010167 
000144 




MOV 


Rl.TRKOFF 




SSAVE IT 


37 


000174 


000412 




BR 


et 




!G0 SAVE PARAMETERS 


38 














JAND START 


39 
















40 






i SPECIAL FUNCTION REOUESTr 


SET 


TRACK AND SECTOR AND 


41 
42 






i BYTE 


COUNT 









The routine passes a 65-word buffer. The first word is if there is no deleted 
data mark. 



43 000176 


000305 


7»! 


SUAB 


R5 


44 










45 000200 


150205 




BISB 


R2.R5 


46 










47 000202 


012702 
000200 




MOV 


♦128. ,R2 


48 










49 




.IF EQ 


MMGtT 




50 






CLR 


<R0) + 


51 










52 




.IFF 






53 000206 


016704 
177576 




MOV 


DXCQE»R4 


54 










55 000212 


005046 




CLR 


-(SP) 


56 










57 000214 


004777 
000710 




JSR 


PCre$PTWRD 


58 










59 000220 


005720 




TST 


<R0) + 


60 










61 




.ENtiC ; 


EQ MMGfT 




62 










63 




) MERGE 


HERE TO 


START OPERATION 


64 











SPUT PHYSICAL SECTOR IN 

r HIGH BYTE 

} AND PHYSICAL TRACK IN 

! LOU BYTE 

fSET THE BYTE COUNT TO 

f 128 

(CLEAR DELETED DATA FLAG 
j WORD J BUMP USER ADDR 

fPOINT TO QUEUE ELEMENT 

fAT O.BLKN 

(STACK A ZERO AND STORE 
i IT IN FIRST WORD OF 
i BUFFER. NOTE THAT 

i Q.BUFF GETS BUMPED BY I 
(ADD 2 TO OUR COPY OF 
(USER BUFFER ADDRESS 



Save the user virtual buffer Eiddress, the track, the byte count, and the 
PABl value for XM systems: 



65 


000222 


010027 


8$J 


MOV 


RO»(PC)+ 


66 


000224 


000000 


BUFRAD, 


.WORD 





67 












68 


000226 


010567 
000140 




MOV 


R5, TRACK 


69 


000232 


010227 




MOV 


R2r (PC)+ 


70 


000234 


000000 


bytcnt: 


.UORD 





71 












72 






,IF NE 


MMG*T 




73 


000236 


005723 




TST" 


(R3) + 


74 












75 


000240 


011327 




MOV 


eR3»(PC)+ 


76 












77 


000242 


000000 


PARVAL! 


.UORD 





78 












79 






.ENDC ( 


NE MMG»T 




80 


000244 




.IF DF 


.BR 
RXINIT 


RXINIT 








.IF NE 


.-<RXINIT> 



SAVE BUFFER ADDRESS 
I USER VIRTUAL BUFFER 
ADDRESS 
SAVE IT FOR STARTING I/O 

AND BYTE COUNT. 
; BYTE COUNT FOR 
TRANSFER 

(SKIP THE COMPLETION 

(ROUTINE ADDRESS 

(SAVE THE PARI VALUE 

(FOR MAPPING USER BUFFER 

( ! PAR VALUE FOR 

( MAPPING USER BUFFER 

(GO TO FORK LEVEL AND 
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.ERROR iHQT AT LOCATION -RXINIT" 

.ENDC 

• ENDC 



81 
82 
83 



f START IT UP 



.DSABL LSB 

.SBTTL START TRANSFER OR RETRY 

.ENA6L LSB 



The calculations are done; the routine can now start an operation or a retry. 
Before it starts, however, it arranges transfer routines for interrupt entry. 
To get to the ready state, force one interrupt, then return to 1$: 



5 000244 



7 000252 

8 

9 000256 
10 
11 
12 000260 

13 

14 000264 

15 000270 
16 

17 000272 

18 



012767 RXINIT! hOV 

177600 

000204 



016704 
000166 



000446 



005067 1$! 
000172 

032700 
000002 
001010 

004067 2»! 
000476 



Moy 

BR 

CLR 

BIT 
BNE 
JSR 



H*- 8*>RXIRTN 

RXCSA»R4 

RXIENB 

RXIRTN 

*2,R0 

3t 

ROfSILOFE 



fSET RETURN AFTER INITIAL 



i INTERRUPT 

(ENSURE THAT WE POINT TO 

(THE CSR 

*G0 INTERRUPT » RETURN TO 

!1» LATER 

(ASSUME RETURN AFTER 

SREAII INTERRUPT 

(READ OR WRITE FUNCTION? 

!IF REAIlf GO FILL THE 
iSILO FROM DISK 
HJRITE» LOAD THE SILO 

(FROM THE USER BUFFER 



Parameters for SILOFE routine: 



19 


000276 


000001 


20 


000300 


112215 


21 






22 


000302 


010115 


23 






24 


000304 


012767 
000052 
000144 



.WORD CSFBUFICSGO 
MOMB (R2)+>eR5 



MOM 



MOM 



RlrSRS 



25 



JFILL BUFFER COMMAND 
(MOVB TO BE PLACED 
i IN LINE IN SILOFE 
;ZERO-FILL INSTRUCTION 
>FOR SHORT WRITES 
*10«-atrRXIRTN )SET RETURN AFTER WRITE 



! INTERRUPT 



The following routine changes a sector number to an interleaved sector 
number: 



26 


000312 


116702 
000055 


3$ 


27 


000316 


003014 




28 








29 


000320 


162702 
177762 




30 








31 


000324 


003003 




32 








33 


000326 


062702 
000014 




34 








35 


000332 


000261 




36 


000334 


006102 


4* 


37 









MOVE 


SECT0R»R2 


B6T 


5$ 


SUB 


*-14. »R2 


BGT 


4$ 


ADD 


*12. jR2 


SEC 




ROL 


R2 



SGET THE SECTOR NUMBER 

fPOSITIVE MEANS SPFUN, 
(DON'T INTERLEAVE 
fADD 14 TO DO INTER- 

(LEAVING 

fIF > Or MAP -13!-1 TO 

t 2!26r NOTE C=0 

i ELSE MAP -26!-14 TO 

i lt25 

iADD 1 WHEN DOUBLING 
(DOUBLE AND INTERLEAVE> 
(SECTOR 1!26 
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38 


000336 


062702 




ADD 


<PC)+fR2 


39 












40 


000340 


000000 


TRK0FF5 


.WORIi 





41 












42 












43 


000342 


003002 




BGT 


5* 


44 


000344 


062702 
000032 




ADD 


♦26.. R2 


45 












46 


000350 


010014 


5«: 


hOV 


R0>@R4 


47 












48 


000352 


105714 


6t; 


TSTB 


eR4 


49 


000354 


001776 




BEQ 


6« 


50 


000356 


100146 




BPL 


RXRTRY 


51 












52 


000360 


010215 




MOM 


R2feR5 


53 


000362 


105714 


7»: 


TSTB 


eR4 


54 


000364 


001776 




MB 


7« 


55 
56 
57 


000366 


100142 




BPL 


RXRTRY 


000370 


112715 




MOVB 


(PC)+,eR5 


58 


000372 


000 


track: 


.BYTE 





59 


000373 


000 


sector: 


.BYTE 






60 



fADD IN THE TRACK OFFSETt 

(SECTOR -35:26 

i I TRACK OFFSET = 

i TRACK*6 MOD 26» 

} RANGE -26;0 

5N0 MODULUS PROBLEMS 

;FIX to put SECTOR IN 

Si;26 RANGE 

JSET THE FUNCTION IN THE 
(FLOPPY CONTROLLER 
SUAIT FOR 
(TRANSFER READY 
(TRANSFER DONE WITHOUT 
(TRANSFER READY, ERROR 
(SET SECTOR NUMBER 
(WAIT AGAIN FOR 
(TRANSFER READY 
(TRANSFER DONE WITHOUT 
(TRANSFER READY, ERROR 
(SET THE TRACK NUMBER 
(TRACK NUMBER 
(SECTOR NUMBER, KEPT < 
(UNLESS SPFUN 



Start; the operation and return to the monitor: 



61 000374 052714 RXIENB: BIS 

000100 
62 
63 

64 000400 000207 RTS 

65 
66 
67 000402 016704 RXERR: MOW 

177402 
6B 

69 000406 052754 BIS 

000001 

70 000412 000511 BR 
71 



#CSINT,eR4 

PC: 

DXCQE,R4 

*HDERR*,0-(R4) 
13* 



(SET IE TO CAUSE AN 

(INTERRUPT WHEN DONE 
(IS UP 

(RETURN, WE'LL BE BACK 
(WITH AN INTERRUPT 

(R4 -> CURRENT QUEUt- 

(ELEMENT 

(SET HARD ERROR IN CSW 

(EXIT ON HARD ERROR 



Interrupt Service Section 

The .DRAST macro: 



72 000414 



.DRAEIT DX,5,RXAERT 
.GLOBL tINPTR 
.IF B <RXABRT> 

RTS •/.? 
.IFF 



(AST ENTRY POINT TABLE 



The abort entry point: 



000414 000521 BR 

.ENDC 
000416 004577 DXINT:! JSR" 

000514 
000422 000100 .WORD 



RXABRT 

%5,etINPTR 

"C<5«"040>S"0340 



Drop to fork level rather than device priority because the routine is lengthy 
and it needs all the registers. 
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73 000424 
000424 



004577 
000510 
000430 0004ii2 



.FORK 

JSR 



.UORO 



nXFBLK 
X5.e*FKPTR 

DXFBLK - . 



74 



(REQUEST FORK LEVEL 



(IMMEDIATELY 



Load registers; if the transfer is successful, this routine dispatches to the 
appropriate section for this interrupt. The three possibilities are: the first 
interrupt occurred; a read operation completed; a write operation com- 
pleted. (A seek operation is treated as a zero-length read.) 



75 


000432 


012700 




Moy 


<PC)+jR0 


76 












77 


000434 


000000 


RXFUN2: 


.UORIi 





78 












79 


000436 


012703 
000200 




MOV 


♦128. ,R3 


80 


000442 


012704 




MOV 


(PC)+fR4 


81 












82 


000444 


177170 


RXCSAt 


.UDRD 


DXJCSR 


83 


000446 


010405 




MOV 


R4,R5 


84 












85 


000450 


005725 




TST 


<R5) + 


86 












87 


000452 


100510 




BHI 


RXRTRY 


88 


000454 


062707 




A 11(1 


<F'C) + »PC 


89 












90 


000456 


000000 


RXIRTN5 


. UORII 





91 












92 


000460 




8«; 






93 













jQET A VERY USEFUL FLAG 

iUORIi 

! ! READ OR URITE COMMAND 

} ON CORRECT UNIT 

5L0AD A HANDY CONSTANT 

JOET ADDRESS OF RX 

(CONTROLLER 

•f i ADDRESS OF CONTROLLER 

(POINT R5 TO RX DATA 

(BUFFER 

(CHECK FOR ERROR. R5 -> 

(DX REGISTER WITH ERROR 

(ERROR. PROCESS IT 

(NO ERROR. DISPATCH 

(AFTER INTERRUPT 

(OFFSET TO INTERRUPT 

(CONTINUATION 

(REFERENCE TAG FOR 

(RETURN OFFSETS 



Verify that the read interrupt code follows 8$: 



1 000460 



4 000460 005700 



.ASSUME . EQ 8* 

.IF EO <.>-<8»> 

. IFF 

.ERROR C. EQ 8f IS NOT TRUE 

.ENDC 



TST 



RO 



(MUST FOLLOW DISPATCH 



(CODE 

(READ. IS THIS A SPECIAL 
(FUNCTION? 



The silo is a 128-byte (decimal) storage area in the diskette logic. 



6 000462 100016 

7 

8 000464 032715 
000100 

9 
10 

11 000470 001413 
12 



BPL 9* 

BIT *ESDD.eR5 

BED 9« 



(NO. SIMPLY EMPTY THE 
(SILO THAT WAS JUST READ 
(IF SPFUN READ, IS 

(DELETED DATA FLAB 

(PRESENT? 

(NOPE, JUST EMPTY THE 

(SILO 



This routine puts a 1 in the first word of the user buffer if a deleted data 
mark was present on a .SPFUN read. 



13 
14 
15 
16 



,IF EQ MMG»T 
MOV 

INC 



BUFRAD.R2 
-(R2) 



(GET ADDRESS OF USER 

(BUFFER AREA 

(SET FLAG WORD TO 1 TO 
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17 












18 






• IFF 






19 


000472 


010401 




Moy 


R4rRl 


20 


000474 


016704 
177310 




MOM 


DXCQE)R4 


21 


000500 


012746 
000001 




MOM 


*lr-(SP) 


22 












23 


000504 


162764 
000002 
000004 




SUB 


*2r(}.BUFF-0 


24 












25 


000512 


004777 
000412 




JSR 


PC,e«PTWRD 


26 












27 












28 


000516 


010104 




MOV 


RlrR4 


29 






.ENDC 


!EQ MMQ*T 




30 


000520 


004067 
000250 


9»! 


JSR 


ROfSILOFE 


31 












32 


000524 


000003 




.WORD 


CSEBUFfCSGO 


33 


000526 


111522 




MOMB 


eR5> (R2)+ 


34 












35 


00CI530 


011502 




MOM 


eR5fR2 


36 













J INDICATE DELETED DATA 

?SAVE R4 

(POINT TO QUEUE ELEMENT 

JSTACK A 1 TO PUT INTO 

;flag UORD 



fBACK TO FIRST WORD. 
(STORE IN 1ST WORD. 

(Q.BUFF IS AGAIN 
(ORIGINAL+2 
(RESTORE R4. 

(FOR READj MOME THE DATA 

( FROM SILO TO BUFFER 

J EMPTY BUFFER COMMAND 

i MOMB TO BE PLACED IN 

■f LINE IN SILOFE 

i DATA SLUFFER TO BE 

( USED FOR SHORT READ 



This jpoint marks the successful completion of one sector for a read or write 
operation. The next routine increments the pointers for the next interleaved 
sector. 



37 


000532 


105267 
177635 


38 






39 


000536 


001012 


40 


000540 


062767 
163001 
177624 


41 






42 


000546 


062767 
000006 
177564 


43 


000554 


003403 


44 






45 


000556 


162767 
000032 
177554 



10*: 



INCB 


SECTOR 


BNE 


11* 


ADD 


#-26.*400+l 


ADD 


*6fTRK0FF 


BLE 


11* 


SUB 


♦26.»TRK0FF 



(RETURN HERE AFTER WRITES. 

(BUMP SECTOR NUMBER 

(NOT OFF END OF TRACK YET 



(NEXT TRACK 

(BUMP TRACK OFFSET MALUE 



(OK IF STILL IN RANGE 

(-25:0 

(RESET TO PROPER RANGE 



46 



(MOD 26 



The following routine increments the buffer address by 128 bytes, and 
reduces the byte count by 128. If the operation is not complete, it transfers 
another sector. 



47 


000564 




11*: 








43 
49 
50 






.IF EQ 

.IFF 


MMG*T 
ADD 


R3i 


rBUFRAD 


51 


000564 


062767 
000002 
177450 




ADD 


*2i 


iPARVAL 


52 

53 
54 


000572 


160367 
177436 


.ENDC i 


lEQ MMG*T 
SUB 


R3, 


rBYTCNT 



56 000576 101230 



BHI 



1* 



(UPDATE BUFFER ADDRESS 
(CHANGE MAP TO BUMP 

(ADDRESS FOR NEXT TIME 
(REDUCE THE AMOUNT LEFT 

(TO TRANSFER 

(LOOP IF WE ARE NOT DONE 
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The transfer is done. The routine sets the byte count to 0, and goes to 12$ if 
this was a read or a special function operation. 



57 


000600 


005067 
177430 


CLR 


BYTCNT 


58 










59 


000604 


032700 
100002 


BIT 


*2!SPFUNC»R0 


60 










61 


000610 


001004 


BNE 


12* 


6 2 











JFIX BYTE COUNT SO THAT 

JURITES ARE ALL 0-FILLS 
JREAD OR SPECIAL FUNCTION 

fDPERATION? 

fIF SOj no ZERO-FILLINGf 

$S0 UE'RE DONE 



The operation was a write. The routine may need to zero-fill up to three sec- 
tors (see FILLCT above). 



63 


000612 


062727 
040000 




ADD 


t 


64 












65 


000616 


000 




.BYTE 





66 


000617 


000 


FILLCT! 


.BYTE 





67 












68 


000620 


103224 




BCC 


2 


69 












70 


000622 




12»: 






71 












72 






• IF NE 


ERL»G 





*040000i (PC)+ 



»CHECK ORIGINAL UORH 

! COUNT FOR * OF SECTORS 
J FILLER 

r ! ORIGINAL WORD COUNT 
f LOU BYTE IN HIGH BYTE 
»YES» LOOP FOR ZERO- 
JFILLING ON URITE 
fAHHj A SUCCESSFUL 
f TRANSFER IS DONE 



Log a successful transfer: 



73 


000622 


012704 
011377 




MOV 


*DX*COD»400+3 


77jR4 {SET UP R4 = ID/-1 


74 


000626 


016705 
177156 




HOV 


DXCQE.R5 


(AND R5 -> CURRENT 


75 












iOUEUE ELEMENT 


76 


000632 


004777 
000274 




JSR 


PC»(?*ELPTR 


{CALL ERROR LOGGER TO 


77 












(REPORT SUCCESS 


78 






.ENDC 


fEQ ERL*G 






79 


000636 


005077 
177602 


13t! 


CLR 


eRXCSA 


(DISABLE FLOPPY 


80 












{INTERRUPTS 



I/O Completion Section 



The .DRFIN macro: 



81 000642 




i4t: 

.GLOBL 


.DRFIN 
DXCQE 


DX 


000642 


010704 




MOV 


%7,Z4 


000644 


062704 
177144 




ADD 


♦ DXCOE-^. , 


000650 


013705 
000054 




MOy 


e*"054.X5 


000654 


000175 
000270 




JMP 


B''0270<5) 



y.A 



{GO TO I/O COMPLETION 



The abort routine: 



1 { ABORT TRANSFER 

3 000660 012777 RXABRT ! MOV *CSINIT » ORXCSA {PERFORM AN RXll 
040000 
177556 
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000(46A 



005067 
000212 



CLR 



DXFELK+2 



JINITIALIZE 

5 CLEAR FORK BLOCK TO 

JAVOID A rUSPATCH 



Go to .DRFIN (no error logging): 



7 000672 000763 

8 

9 
10 
11 
12 
13 
14 



BR 



.DSABL LSB 



14t 



.DRyiE 
.ENDC JNE DXTtO 



.riXtVC2.DXINT 



(AND FINISH UP THIS I/O 



.IF NE DXTtO 

.DRVTB DXiDXtVECiDXINT 



If th(;re was an error, log it: 



i TRANSFER ERROR HANDLING 



3 000674 
4 

5 000674 

6 000676 



a 000702 

9 000704 

10 000706 

11 000710 



13 000714 

14 000720 

15 000722 

16 000724 



17 

18 000730 



19 

20 000734 



22 000740 

23 000742 



24 000746 

25 000752 



26 
27 



010703 
062703 
000214 

010302 
011423 
011523 
012714 
000017 

032714 
000040 
001775 
011513 
012703 
004003 
004003 

012704 
011000 

156704 
177056 

105304 
016705 
177042 
004777 
000160 
016704 
177466 



RXRTRY! 
.IF NE 



1*! 



ERL»G 

MOV PC.R3 

ADD tDXRBUF- 



MOV 
MOV 
MOV 
MOV 



BIT 

BEQ 
MOV 
MOV 



MOV 



BISB 



DECB 
MOV 



JSR 
MOV 



fR3 



fR3 



LOCATION TO STORE 



jREGISTER INFO. 
R3fR2 SSAVE IN R2 FOR LATER 

@R4><R3>+ f STORE RXCS 
eR5>(R3)+ JSTORE STATUS RXES 
♦ CSMAIN!CSG0,I?R4 (READ ERROR REGISTER 



*CSnONEieR4 



;(N0 INTERRUPTS) 

fUAIT FOR READ COMPLETION 



1* 

eR5reR3 SSTORE IN BUFFER 

»RETRY*400+DXNREG>R3 rR3 = ♦ OF REGS 



*DX*C0D*400fR4 
RXTRYrR4 



R4 
DXCQEfRS 



PC,e«ELPTR 
RXCSA»R4 



.ENDC iNE ERL*G 



!(L0)/T0TAL RETRIES (HI) 
rR4 = DEVICE ID IN HIGH 

JBYTE 

{AND CURRENT RETRY 

(COUNT IN LOU BYTE 
} -1 FOR THIS ERROR 
!R5 -> QUEUE ELEMENT 

(CALL ERROR LOGGER 

(RESTORE R4 = RXCS 

(ADDRESS 



See if a retry is allowed: 



28 000756 


005367 
177034 


DEC 


RXTRY 


29 000762 


003607 


BLE 


RXERR 


30 000764 


012714 
040000 


MOV 


*CSINIT.eR4 



(SHOULD WE TRY AGAIN? 

(NOPEj REPORT AN ERROR 
(START A RECALIBRATE 



Retry the operation: 
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31 000770 

32 

1 

2 

3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
IS 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 



000167 
177250 



JMP RXINIT JEXIT THROUGH START 

fOPERATION CODE 

.SETTL SILOFE - FILL OR EMPTY THE SILO 

S + 

t SILOFE - FILL OR EMPTY THE SILO. DUMPING OR ZERO- 

) FILLING IF NEEDED 

i 

R3 = 128. 

R4 -> FLOPPY CSR 

JSR ROfSILOFE 
COMMAND} CSFBUFICSGO FOR FILL (URITE) 
CSEBUFICSGO FOR EMPTY (READ) 
FILL/EMPTY INSTRUCTION! <R2 -> USER BUFFER, 

R5 -> RXDB) 
MOVB (R2>+,eR5 FOR FILL <URITE) 
MOVE eR5»<R2)+ FOR EMPTY <READ) 
SLUFF INSTRUCTION! <R1 = Of R5 -> RXDB) 

CLRB eR5 FOR FILL (WRITE) 
MOVB eR5fR2 FOR EMPTY (READ) 

Rl = RANDOM 
R2 = RANDOM 

NOTE! 1. THIS ROUTINE ASSUMES ERROR CAN NOT COME UP 
.DURING A FILL OR EMPTY!! 
2. SEEK DOES A SILO EMPTY, A TIME MASTER 



The diskette deals only in units of 128 decimal bytes. If a request to read is 
for fewer than 128 bytes, the handler reads 128 bytes and sloughs the extra 
bytes. If a request to write is for fewer than 128 bytes, the handler zero-fills 
to reach 128 bytes. 



29 


000774 


012014 


SILOFE! 


MOV 


(R0)+,eR4 


5INITIATE FILL OR EMPTY 


30 












{BUFFER COMMAND 


31 


000776 


012067 
000042 




MOV 


(R0)+,3* 


JPUT CORRECT MOV 


32 












{INSTRUCTION IN FOR 


33 












fFILL/EMPTY 


34 


001002 


012067 
000056 




MOV 


(R0)+,5« 


SPUT IN INSTRUCTION TO 


35 












! SLUFF DATA 


36 


001006 


016701 
177222 




MOV 


BYTCNTjRI 


(GET BYTE COUNT 


37 


001012 


001421 




BEQ 


4« 


(IF ZERO, WE ARE SEEKING 


38 












(OR ZERO FILLING 


39 






.IF NE 


MMG»T 






40 


001014 


013746 
172342 




MOV 


8»KISAR1,-(SP) 


(SAVE THE CONTENTS OF 


41 












(PARI 


42 


001020 


016737 
177216 

172342 




MOV 


PARVAL,e*KISARl 


(MAP THE BUFFER VIA PARI 


43 






.ENDC i 


NE MM6$T 






44 


001026 


020103 




CMP 


R1,R3 


(IS THE BYTE COUNT 


45 












(<= 128? 


46 


001030 


101401 




BLOS 


It 


(OK IF SO 


47 


001032 


010301 




MOV 


R3,R1 


(DO ONLY 128 BYTES AT A 


48 












(TIME 


49 


001034 


016702 
177164 


1»! 


MOV 


BUFRAD,R2 


(GET USER VIRTUAL BUFFER 


50 












(ADDRESS IN R2 


51 


001040 


105714 


2«! 


TSTB 


eR4 


(WAIT FOR 


32 


001042 


100376 




BPL 


2« 


(TRANSFER READY 


53 


001044 


000000 


3*! 


HALT 




(INSTRUCTION TO MOV OR 


54 












(SLUFF DATA FROM 


55 


001046 


005301 




DEC 


Rl 


(CHECK FOR COUNT DONE 


56 


001050 


003373 




BGT 


2» 


(STILL MORE TO TRANSFER 
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57 

58 001052 012637 
172342 
59 



.IF NE 



MMGtT 
MQV 



<SF>+jB*KISAR1 (RESTORE PARI 



•ENDC >NE MM6*T 



The alough routine: 



60 001056 

61 

62 001060 

63 

64 001062 

65 001064 
66 

67 001066 

68 

69 001070 



3 

4 

5 001072 

6 

7 001074 

8 

9 001076 
10 

11 001100 
12 
13 

14 001102 

001104 

001106 

001110 

15 

16 

17 001112 
13 



105714 

003003 

001775 
000000 

000773 

000200 



100006 
077776 
100000 
000000 



000000 
000000 
000000 
000000 



4«: 



5«! 



6t; 



TSTB 


(>R4 


BGT 


6t 


BEQ 


4$ 


HALT 




BR 


4$ 


RTS 


RO 



!UAIT FOR TRANSFER READY 

$0R TRANSFER DONE 

(TDNE UP UITH NO TRDYr 

iSO ALL DONE 

(LOOP 

(TRANSFER READYf SO 

fSLUFF DATA 

(LOOP TO SLUFF MORE 



(RETURN 

•SBTTL TABLESi FORK BLOCK, END OF DRIVER 

( CHANGES TO CSR CODE FOR SPECIAL FUNCTIONS 

.WORIi CSURTD-CSRD+SPFUNC (375t READ+GO -> 

(WRITE DELETED+GO 
.WORIi CSWRT-CSRD+SPFUNC (376! READ+GO -> 

(URITE+GO 
.WORII CSRD-CSRD+SPFUNC (377! READ+60 -> 

(READ+GO 
CHGTBL! .WORD (READ/WRITE STAY THE 

(SAHE 



DXFBLK! .WORIi 0.0»0»0 



.IF NE ERL*CI 

DXRBUF! .BLKU DXNREG 

.ENDC (NE ERL*G 



(DX FORK QUEUE ELEMENT 



(ERROR LOG STORAGE 



Primary Driver 



.SBTTL BOOTSTRAP DRIVER 



The .DRBOT macro: 

3 001120 



.DRBCIT DXrBOOTliREAD 



Termination Section 



The DREND macro generated by .DRBOT: 



001120 




.DREND DX 


001120 




.PSECT DXDVR 

.IIF NDF DX«END. DX*END! 

.IF EO .-DXJIEND 


001120 




DX«END! : 

.IF NE MMG*T 


001120 


000000 


tRLPTR!! .WORD 


001122 


000000 


♦MPPTR!! .WORD 


001124 


000000 


♦GTBYT!! .WORD 
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001126 


000000 


iPTBYTI 


:: .MDRD 





001130 


000000 


tPTURDl 
.ENDC 
.IF NE 


:; .WORD 
ERL*G 





001132 


000000 


$ELPTR! 
.ENDC 
.IF NE 


: .UORD 
TIM»IT 





001134 


000000 


»TIMIT! 
.ENDC 


: .UORD 





0011.36 


000000 


tINPTR! 


: .yoRD 





001140 


000000 


»fkptr: 

.GLOBL 


: .WORD 
DXSTRT 






The following line marks the end of the loadable portion of the handler. It is 
used to determine the handler's length. 







001142' 


DXEND == . 

.ENDC 

.IIF NDF TPS. 

.IIF NDF TPBr 


TPS=177564 
TPB=177566 






000012 


LF = 12 








000015 


CR^-15 








001000 


B$B00T=1000 








01.14716 


BtDEVN=4716 








004722 


B!tDEVU = 4722 








004730 


BtREAD=4730 
.IF EC) MMGtT 
BtDNAM="RDX 
.IFF 








016330 


BtDNAM="RDXX 
.ENDC 






000200 


000062 


.ASECT 

.=62 






000062 


000000' 


. WORD 


DXBOOTtDXBEN 




000064 


001000 








000066 


000224 








000000 




.PSECT DXBOOT 






000000 


000240 


dxboot::nop 




4 

3 


000002 


000414 


BR 


BOOTl 




000014' 


= DXBOOT+14 


6 


000014 


000120 


.WORD 


READS-DXBOOT 


7 


000016 


000340 


.WORD 


340 


8 


000020 


000070 


.WORD 


WAIT-DXBOOT 


9 


000022 


000340 


.WORD 


340 


10 











Locations 34 through 52 are reserved for DIGITAL. 



11 




000034' 


t 


= DXBOOT+34 


!34-52 USEABLE 




12 


000034 


116067 


BOOTl : 


Moyn 


UNITRD-DXBODT(RO)rRDCMD (SET READ 








000056 
















000066 












13 












(FUNCTION FOR CORRECT 


14 












(UNIT 




15 


000042 


011706 


REETRY! 


Moy 


epcsp 


ilNIT SP WITH NEXT 




16 












(INSTRUCTION 




17 


000044 


012702 




MOV 


♦200. R2 


(AREA TO READ IN NEXT 






000200 












IB 












(PART OF BOOT 




19 


000050 


005000 




CLR 


RO 


(SET TRACK NUMBER 




20 


000052 


000446 




BR 


B2« 


(OUT OF ROOM HERE. 


BO TO 


21 












(CONTINUATION 




A. «'.. 

23 




000056' 


^ 


= IiXBOOT + 56 






24 


000056 


007 


UNITRD! 


.BYTE 


CSGO+CSRD 


(READ FROM UNIT 0. 


SETS 


25 












(WEIRD BUT OK PS 




26 
27 
28 


000057 


027 




.BYTE 


CSGO + CSRDt-CSUNIT 


(READ FROM UNIT 1 






000070' 


, 


= DXBOOT+70 


(PAPER TAPE VECTORS 


5 
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29 000070 
30 

31 000072 

32 000074 

33 000076 
34 

35 

36 000120 

37 000124 
38 

39 000126 

40 000130 
41 

42 000132 

43 000134 
44 

45 000136 

46 000140 
47 

48 000142 

49 000144 

50 
51 
52 
53 000150 



005714 WAIT! 



TST 



000152 
000154 



7 



54 
55 
56 

57 000156 

58 000160 

59 000162 
60 

61 000164 

62 

63 000166 

64 

65 000170 

66 000172 

67 000174 
68 

69 000176 
70 

71 000200 
000202 

73 000204 

74 000206 

75 000210 



76 000216 
7 7 

78 000220 

79 000222 
80 

81 

82 000224 

83 000226 

84 000230 

85 000232 

86 000234 
37 000236 
88 000240 



89 

90 000246 



91 

92 000254 



93 

94 000260 



BEQ 

BMI 

RTIRET! RTI 



reads: 



RUCMD! 



001776 
100762 
000002 

000120' 
012704 
177170 
010405 

012725 
000000 

000004 
010315 

000004 
010015 

000004 
012714 
000003 



000220 BROFFS 



eR4 



WAIT 
REETRY 



SIS TR, ERR J DONE UP? 
«INT ENB CAN'T BE 
{LOOP TILL SOMETHING 
JSTART AGAIN IF ERROR 
{RETURN 



= DXBOOT+120 
HOy *DX*CSR»R4 



!R4 



RX STATUS REGISTER 



000004 
105714 
100350 

111522 
005301 
003372 

005002 

000770 

010601 
005200 
011703 

000003 

122323 
000003 
122323 
000003 
032767 
000020 
177712 
001173 

005000 
000571 



012737 
000167 
000150 
012737 
000214 
000152 
012737 
000300 
004730 

012737 
000416 
000030 

005037 
000044 

005767 
000346 



RDX: 



B2«! 



MOV 



MOV 
.UORD 



lOT 
MOV 



lOT 
MOV 



lOT 
MOV 



lOT 

TSTB 

BPL 

MOVB 
DEC 

BGT 

CLR 

BR 

MOV 
INC 
MOV 



!R5 WILL POINT TO RX 
(IiATA BUFFER > 
(INITIATE READ FUNCTION 
SGETS FILLED WITH READ 
{COMMAND 

(CALL WAIT SUBROUTINE 
(LOAD SECTOR NUMBER INTO 
(RXDB 

(CALL WAIT SUBROUTINE 
(LOAD TRACK NUMBER INTO 
(RXDB 

(CALL WAIT SUBROUTINE 
*CSG0+CSEBUF.eR4 (LOAD EMPTY BUFFER 



R4,R5 



(PC)+r <R5)+ 




R3ieR5 



ROjSRE 



READF- 



0R4 
RTIRET 

(?R5. (R2) + 

Rl 

RDX 

R2 

RDX 

SPiRl 

RO 

BPC.R3 



(FUNCTION 
(USE FOR C 
(OFFSET 
(CALL WAIT 
(IS TRANSF 
(BRANCH IF 
(MUST BE L 
(MOVE DATA 
(CHECK BYT 
(LOOP AS L 
(COUNT NOT 
(KLUDGE TO 
(IF SHORT 
(LOOP 



INTO RXCS 
OMPUTING BR 

SUBROUTINE 
ER READY UP? 

NOT, SECTOR 
OADED 

BYTE TO MEMORY 
E COUNT 
ONG AS WORD 

UP 

SLUFF BUFFER 
Wn CNT 



BPT 
(SECTOR 2 OF 
B00T2! CMPB 
BPT 
CMPB 
BPT 
BIT 



BNE 



RX BOOT 

(R3)+, (R3)+ 

(R3) + > <R3) + 

♦CSUNIT.RDCMD 



BOOT 



CLR 
BR 



RO 
BOOT 



READ! 



MOV (PC) + f(?<PC) + 

•WORD 167 

,WORD RDX-DXBOOT 
MOV 

.WORD 

.WORD 



(SET TO BIG WORD COUNT 
(SET TO ABSOLUTE TRACK 
(ABSOLUTE SECTOR 3 FOR 
(NEXT PART 
(CALL READS SUBROUTINE 

(BUMP TO SECTOR 5 
(CALL READS SUBROUTINE 
(BUMP TO SECTOR 7 
(CALL READS SUBROUTINE 
(CHECK UNIT ID 



(BRANCH IF BOOTING UNIT 

(1, R0=1 

(SET TO UNIT 

(NOW WE ARE READY TO DO 

(THE REAL BOOT 

(MODIFY READ ROUTINE 



MOV 



MOV 



CLR 



TST 



(PC)+r0(PC)+ 

READF-RDX-4 

RDX-DXBOOT+2 

*READl-DXBOOTFe*BtREAD (CALLS TO B»READ 



(WILL GO TO READl 
*TRWAIT-DXB00T,I?»20 (LETS HANDLE ERRORS 



(5*JSW 



HRDBOT 



95 



(DIFFERENTLY 

(CLEAR JSW SINCE THE DX 

(BOOT IN SYSCOM AREA 
(DID WE REACH HERE VIA A 

(HARDWARE BOOT? 
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96 


000264 


001405 


97 






98 


000266 


013703 
004722 


99 


000272 


116367 
000056 
177630 


100 






101 


000300 


006300 


102 






103 


000302 


006300 


104 


000304 


006301 


105 






106 


000306 


010046 


107 


000310 


010003 


108 






109 


000312 


010004 


no 


000314 


005000 


111 


000316 


000402 


112 






113 


000320 


162703 
000027 


114 






115 


000324 


005200 


116 






117 


000326 


162704 
000032 


118 


000332 


100372 


119 


000334 


022704 
177762 


120 






121 


000340 


006103 


122 


000342 


162703 
000032 


123 






124 


000346 


100375 


125 






126 


000350 


062703 
000033 


127 






128 


000354 


000003 


129 


000356 


012600 


130 


000360 


005200 


131 


000362 


005701 


132 






133 


000364 


003350 


134 






135 


000366 


000207 


136 






137 


000370 


005714 


138 


000372 


001776 


139 


000374 


100533 


140 


000376 


105714 


141 


000400 


100011 


142 


000402 


111522 


143 


000404 


005301 


144 


000406 


003370 


145 


000410 


012702 
000001 


146 






147 






148 


000414 


000765 


149 






150 


000416 


005714 


151 


000420 


100521 


152 


000422 


001775 


153 


000424 


000002 


154 






155 




000606 


156 


000606 


012706 
010000 


157 


000612 


010046 


158 


000614 


012700 
000002 


159 






160 


000620 


012701 
002000 



READli 



1$; 



3«) 



3$: 



4»! 



REAIiF! 



BEQ READl 

MOV 0*B«DEVU»R3 

MOMB UNITRD-riX»00T<R3) fRDCMD (STORE UNIT 



.'YES. DON'T SET UP UNIT 

* NUMBER 

iUOf SET UP UNIT NUMBER 



ASL 

ASL 
ASL 

MOy 

Moy 

MOV 
CLR 
BR 

SUB 



RO 

RO 
Rl 

RO>-(SP> 
R0jR3 

R0jR4 

RO 

3$ 

t23. rR3 



INC 


RO 


SUB 


*26.fR4 


BPL 


2« 


CMP 


*-14. rR4 


ROL 


R3 


SUB 


»26. iR3 


BPL 


4$ 


ADD 


*27.,R3 


BPT 




MOV 


(SP)+fRO 


INC 


RO 


TST 


Rl 


EGT 


1* 


RETURN 




TST 


BRA 


BEO 


READF 


BMI 


BIOERR 


TSTB 


eR4 


BPL 


READFX 


MOVB 


BR5> (R2)+ 


DEC 


Rl 


BGT 


READF 


MOV 


*1fR2 



BR 



READF 



TRWAIT! TST BR4 

BMI BIOERR 

BEQ TRWAIT 

READFX! RTI 

= DXBOOT+606 

BOOT! MOV *10000iSP 

MOV RO»-<SP) 

MOV ♦2»R0 



MOV 



*<4*400>.R1 



SNUMBER 

(CONVERT BLOCK TO LOGICAL 

iSECTOR 

<LSN=BL0CK*4 

5MAKE WORD COUNT BYTE 

{COUNT 

SSAVE LSN FOR LATER 

>UE NEED 2 COPIES OF LSN 

iFOR MAPPER 

fINIT FOR TRACK QUOTIENT 
(JUMP INTO DIVIDE LOOP 

(PERFORM MAGIC TRACK 

(DISPLACEMENT 

(BUMP QUOTIENT. STARTS 

(AT TRACK 1 

(TRACK= INTEGER <LSN/26) 

(LOOP - R4=REM<LSN/26)-26 
(SET C IF SECTOR MAPS TO 

(1-13 

(PERFORM 2!1 INTERLEAVE 

(ADJUST SECTOR INTO 

(RANGE -1f-26 

((DIVIDE FOR REMAINDER 

(ONLY) 

(NOW PUT SECTOR INTO 

(RANGE 1-26 

(CALL READS SUBROUTINE 

(GET THE LSN AGAIN 

(SET UP FOR NEXT LSN 

(WHATS LEFT IN THE WORD 

(COUNT 

(BRANCH TO TRANSFER 

(ANOTHER SECTOR 



( ERROR f DONE? OR TR UP? 

(BR IF NOT 

(BR IF ERROR 

(TR OR DONE? 

(BR IF DONE 

(MOVE DATA BYTE TO MEMORY 

(CHECK BYTE COUNT 

(LOOP IF MORE 

(SLUFF BUFFER IF SHORT 

(WD CNT 

(DON'T DESTROY LOC 

(LOOP 

(ERROR, DONEj OR TR UP? 
(HARD HALT ON ERROR 
(BR IF NOT 



(SET STACK POINTER 

(SAVE THE UNIT NUMBER 
(READ IN SECOND PART OF 

(BOOT 

(EVERY BLOCK BUT THE ONE 
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162 000624 

163 000630 
164 

165 000632 

166 000634 

167 000640 



168 
169 
170 000646 



171 000654 

172 000660 

173 

174 000664 
001142 



012702 
001000 
005027 

000001 
004767 
177364 
012737 
000300 
004730 



012737 
016330 
004716 
012637 
004722 
000137 
001000 



HRDBOTl 



MOM 

CLR 

.UOFID 
JSR 

MOV 

MOV 

MOV 
JMP 



«1000fR2 
(PC) + 



iUE ARE IN 

UNTO LOCATION 1000 

fCLEAR TO SHOW HARDWARE 

(BOOT 

fINITIALLY SET TO 1 

)G0 READ IT IN 



PC > READ 

#READ1-DXB00Tf(?*B*READ (STORE START 

(LOCATION FOR READ 
(ROUTINE 
*B«DNAMre*B»DEVN (STORE RAD50 DEVICE NAHE 

(SP>+»e«B»DEVU (STORE THE UNIT NUMBER 
e#B*BOOT (START SECONDARY BOOT 



.DREND DX 
.PSECT DXBVFi- 
.IIF NDF DX»END. DX$END! 
.IF EQ ,-DXftEND 

nx*END: ! 

•IF NE MMG»T 



000664 



$RLPTR! 


: .WORD 





»mpptr; 


: .WORD 





*GTBYT) 


: .WORD 





*pthyt; 


) .WOliD 





*PTWRD! 


: .WORD 





.ENDC 






.IF NE 


ERL*G 




tELPTR! 


: .WORD 





.ENDC 






.IF NE 


TIMtIT 




tTIMIT; 


; .WORD 





.ENDC 






♦INPTR! 


: .WORD 





tFKPTR! 


: .WORD 





.6L0BL 


DXSTRT 




DXEND = 


:= , 




.IFF 






.PSECT 


DXBOOT 





.IIF LT <DXBi30T-,+664>» .ERROR (PRIMARY BOOT TOO LARGE 



000664 
000670 
000672 

000676 

000702 
000704 

000710 

000714 

000720 
000722 
000724 



000664' . = DXBOOT+664 

004167 BIOERRJ JSR RliREPORT 

000002 

000766 .WORD lOERR-DXBOOT 



012700 
000746 
004167 
000030 
012100 
004167 
000022 
012700 
000762 
004167 
000012 
000005 
000000 
000776 
000726 

000732 



REPORT! MOV 



JSR 



112037 
177566 
105737 
177564 



MOV 
JSR 



MOV 



JSR 



RESET 

HALT 

BR 

repor: 

REPi 



♦BOOTF-DXBOOTfRO 

RlfREP 

(R1)+»R0 
RIfREP 

♦CRLFLF-DXBOOTfRO 

RIfREP 



,-2 
MOVB 

TSTB 



(RO)+Fe»TPB 



etTPS 



000736 100375 

000740 105710 

000742 001371 

000744 000201 



BPL 


REP 


TSTB 


BRO 


BNE 


REPOR 


RTS 


Rl 
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000746 
000762 
000766 

001000 



175 
176 



015 
015 
111 



000001 



BOOTF! 
CRLFLF! 

ioerr: 

OXBEND! 
.ENDC 

• END 



.ASCIZ 
.ASCIZ 
.ASCIZ 
.EVEN 



<cr><lf>'?boot-u- 
<cr><:lf><lf> 

•I/O ERROR' 



::200> 



SYMBOL TABLE 



BIOERR 


000664R 


003 


IiX*COD= 


000022 


RDX 


BOOT 


000606R 


003 


DXtCSR= 


177170 G 


READ 


BOOTF 


000746R 


003 


nx«cs2= 


177174 G 


READF 


BOOTl 


000034R 


003 


DX«END 


001120RG 


002 READFX 


B00T2 


000200R 


003 


DX»VC2= 


000270 G 


READS 


BROFFS= 


000220 




DXtyEC= 


000264 G 


READl 


BUFRAB 


000224R 


002 


EOF* = 


020000 


REETRY 


BYTCNT 


000234R 


002 


ERL»G = 


000001 


REP 


B$BOOT= 


001000 




ESCRC = 


000001 


REPOR 


B*DEVN= 


004716 




ESBD = 


000100 


REPORT 


B*IiEVU= 


004722 




ESriRY = 


000200 G 


RETRY = 


B$BNAM= 


016330 




ESID = 


000004 


RONLYt= 


BtREAIi= 


004730 




ESPAR = 


000002 


RTIRET 


B2t 


000170R 


003 


FILLCT 


000617R 


002 RXABRT 


CHGTBL 


OOllOOR 


002 


FILSTt= 


100000 


RXCSA 


CR 


000015 




HriERRt = 


000001 


RXERR 


CRLFLF 


000762R 


003 


HNDLRt= 


004000 


RXFUN2. 


CSDONE= 


000040 




HRDBOT 


000632R 


003 RXIENB 


CSEBUF= 


000002 




IOERR 


000766R 


003 RXINIT 


CSERR = 


100000 




JSU 


000044 


RXIRTN 


CSFBUF= 


000000 




KISAR1= 


172342 


RXRTRY 


CSGO = 


000001 




LF 


000012 


RXTRY 


CSINIT= 


040000 




MhG»T = 


000001 


SECTOR 


CSINT = 


000100 




PARMAL 


000242R 


002 SILOFE 


CSMAIN= 


000016 




Q*BLKN= 


000000 


SPECL*= 


CSRB = 


000006 




Q«BUFF= 


000004 


SPFUNC= 


CSRBST= 


000012 




Q$COMP= 


000010 


SPFUNt= 


CSRX02= 


004000 




QtCSU = 


177776 


TIMtIT= 


CSTR = 


000200 




QtFUNC= 


000002 


TPB 


CSUNIT= 


000020 




Q»JNUM= 


000003 


TPS 


CSWRT = 


000004 




Q*LINK= 


177774 


TRACK 


CSWRTD= 


000014 




QtPAR = 


000012 


TRKOFF 


DXBEND 


OOIOOORG 


003 


Q*UNIT= 


000003 


TRWAIT 


DXBOOT 


OOOOOORG 


003 


Q*UCNT= 


000006 


UNITRD 


BXCQE 


OOOOIORG 


002 


Q.BLKN= 


000004 


WAIT 


DXDSIZ= 


000756 




Q.BUFF= 


000010 


WONLY*= 


DXEND = 


001142RG 


002 


O.COMP= 


000014 


*ELPTR 


nXFELK 


001102R 


002 


Q.CSW = 


000002 


$FKPTR 


nxiNT 


000416RG 


002 


a.ELGH= 


000024 


«GTBYT 


DXLQE 


000006RG 


002 


Q.FUNC= 


000006 


tlNPTR 


IiXNREG = 


000003 




a.JNUM= 


000007 


tMPPTR 


nXRBUF 


001112R 


002 


Q.LINK= 


000000 


♦PTBYT 


DXSTRT 


OOOOOORG 


002 


Q.PAR = 


000016 


tPTWRD 


tlXSTS = 


102022 




Q.UNIT= 


000007 


tRLPTR 


nXSYS 


000006RG 


002 


Q.UCNT= 


000012 


tTIHIT 


DXT$0 = 


000000 




RDCMB 


000130R 


003 


. ABS. 


000220 
000000 


000 
001 








DXDVR 


001142 


002 








BXBOOT 


001000 


003 








ERRORS DETECTED: 












virtual memory used; 9984 words ( 39 pages) 
dynamic memory available for 73 pages 
,dx/l:me/l:ttm=cnd.dx 



Figure A-3: PC Paper Tape Handler 



000150R 


003 


000224R 


003 


000370R 


003 


000424R 


003 


000120R 


003 


000300R 


003 


000042R 


003 


000732R 


003 


000726R 


003 


000672R 


003 


000010 




040000 




000076R 


003 


000660R 


002 


000444R 


002 


000402R 


002 


000434R 


002 


000374R 


002 


000244R 


002 


000456R 


002 


000674R 


002 


000016R 


002 


000373R 


002 


000774R 


002 


010000 




100000 




002000 




000001 




177566 




177564 




000372R 


002 


000340R 


002 


000416R 


003 


000056R 


003 


000070R 


003 


020000 




001132RG 


002 


001140RG 


002 


001124RG 


002 


001136RG 


002 


001122RG 


002 


001126R6 


002 


001130RG 


002 


001120RG 


002 


001134RG 


002 



3- 
4- 



MACROS AND DEFINITIONS 
DRIVER ENTRY 

^CONDITIONAL FILE FOR HANDLER EXAMPLES 

r 

iCND.MAC 
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6 

7 

8 

9 

10 

11 

12 

13 



$9/4/79 jnc: 

i ASSEMBLE HITH HANDLER 
J18-BIT I/Cif TIME-OUT, 
iFOR HANDLER. 



000001 


MM6tT 


= 1 


000001 


ERLtG 


= 1 


000001 


TIMtIT 


= 1 



.MAC FILE TO ENABLE 
AND ERROR LOGGING 



J18-BIT I/O 
{ERROR LOGGING 
(TIME-OUT 



3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 



TITLE PC V04.00 
IDENT /V04.00/ 

RT-11 HIGH SPEED PAPER TAPE PUNCH AND READER 

<PC11) HANDLER 

COPYRIGHT <C) 1979 BY 
DIGITAL EQUIPMENT CORP0RATI0N» MAYNARD, MASS, 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE 
USED AND COPIED ONLY IN ACCORDANCE WITH THE 
TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF 
THE AB01.IE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY 
OTHER COPIES THEREOF MAY NOT BE PROyiDED|OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND 
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE 
WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS 
A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR 
RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT 
SUPPLIED BY DIGITAL. 



Preamble Section 



.SBTTL MACROS AND DEFINITIONS 
.MCALL .DRDEF 



A value of means punch ancl reader combined; 1 means reader only. 



.IIF NDF PR11*X, PRlltX=0 
.IIF NE PRlltX, PR11*X=1 



JUNLESS SPECIFIED, DO 
JNOT GENERATE READER ONLY 
5F0RCE NON-ZERO VALUE 
!T0 1 



The .DRDEF macro: 



10 000000 



000000 



000001 



000001 



000001 



000000 
000002 
000004 
OOOOOA 
000007 
000007 



.DRDEF PC, 7, <PRlltX*R0NLY»>, 0,177550, 70 

.MCALL .DRAST, .DRBEG, .DRBOT, . DREND , . DRFIN , .DRSET 

.MCALL .DRVTB, .FORK, .QELDF 

.IIF NDF TIMtIT, TIM*IT=0 

NE TIMtIT, TIM*IT=1 

NDF MMGtT, MMG*T=0 

NE MMGtT, MMGtT=l 

NDF ERLtG, ERLtG=0 

NE ERLtG, ERLtG=l 

NE TIMtIT, .MCALL 



.IIF 

.IIF 

.IIF 

.IIF 

.IIF 

.IIF 

.QELDF 

Q,LINK=0 

CSW=2. 

BLKN=4. 

FUNC^A, 

JNUM=7. 

UNIT=7, 



.TIMIO,.CTIMI 
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000010 


B.BUFF="010 






000012 


Q.UCNT="012 






000014 


Q.C0MP="014 








• IRP Xr<LINKfCSW,EiLKNFFUNC.JNUM»UNIT 


(BUFFfUCNTfCOMP 






Q«'X=0.'X-4 








.ENIiR 






177774 


Q»LINK=Q.LINK-4 






177776 


QiCSW=Cl.CSU-'4 






000000 


Q*BLKN=Q.BLKN-4 






000002 


GI»FUNC!=R.FUNC-4 






000003 


Q*JNUM=Q,JNUM-4 






000003 


R«UNIT=Q.UNIT-4 






000004 


QtBUFF=Q.BUFF-4 






000006 


Cl$WCNT = Q.WCNT-4 






000010 


Q«C0MP=Q.C0MP-4 
.IF EQ MMe»T 
0,ELGH="016 
.IFF 






000016 


a.PAR="016 






000012 


Q*PAR="012 






000024 


Q.ELGH="024 
.ENIJC 






000001 


HDERR»=1 






020000 


E0F*=20000 






002000 


SPFUN$=2000 






004000 


HNriLR»=4000 






010000 


SPECLt=10000 






020000 


U0NLY*=20000 






040000 


R0NLYt=40000 






100000 


FILBT»=100000 






000000 


PC»SIZ=0 






000007 


PC$C0D=7 






000007 


PCSTS=<7>!<PR11*X*R0NLY*> 
•IIF NDF PC*CSRf PC»CSR=177550 
.IIF NDF PC*VECi PC*VEC=70 
.6L0BL PC*CSRfPC«VEC 




1 1 

12 000000 




■QELDF 






000000 


Q.LINK=0 






000002 


O.CSU=2. 






000004 


Q.BLKN=4. 






000006 


Q.FUNC=6. 






000007 


Q.JNUM=7. 






000007 


O.UNIT=7. 






000010 


Q.BUFF="010 






000012 


Q.WCNT="012 






000014 


Q.C0MP="014 








.IRP X»<LINK,CSU,BLKNrFUNC.JNUh.UNIT 


»buff.wcnt»comp: 






Q$'X=Q. 'X-4 








.ENDR 






177774 


QtLINK=Q.LINK-4 






177776 


Q«CSW=Q.CSU-4 






000000 


Q*BLKN=Q.BLKN-4 






000002 


Q»FUNC=R.FUNC-4 






000003 


atJNUM=Q, JNUM-4 






000003 


Q$UNIT=Q.UNIT-4 






000004 


Q»BUFF=Q.BUFF-4 






000006 


a*UCNT=Q.MCNT-4 






000010 


Q*C0MP=Q.COMP-4 
.IF EQ hMG*T 
a.ELGH="016 
.IFF 






000016 


O.PAR="016 






00012 


Cl»Pi»iR = '-012 






000024 


(3.ELGH="024 
.ENDC 




13 








14 

16 


177552 


PCB == PC*CSR+2 


JDATA REGISTER 




} PAPER TAPE PUNCH CONTROL REGISTERS 




17 




.IIF NDF PPtVECr PP$VEC == PC«VEC+4 


fPUNCH VECTOR 


18 






$ADDR 


19 




.IIF NDF PP»CSR. PP$CSR == PC«CSR+4 


i PUNCH CONTROL 


20 






^REGISTER 


21 


177556 


PPB = PPfCSR+2 JPUNCH 


DATA BUFFER 


22 
23 


000001 


PR60 = 1 JREADER 


ENABLE BIT 
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24 
25 

26 



000101 PINT = 101 



(INTERRUPT ENABLE BIT 
JAND 60 BIT 



Header Section 



.SBTTL DRIVER ENTRY 



The .DRBEG macro: 



3 000000 






.DRBEG 


PC (DEFINE ENTRY POINT M 


000000 


000052 


.ASECT 
. = 52 










.GLOBL 


PCEND. POINT 


000052 


000324 


.IF B 


.UORD 

<> 


<PCEND-PCSTRT> 


000054 


000000 


.IFF 

.ENDC 
.IF B 


.WORD 
.WORD 

<> 


PCDSIZE 


000056 


000007 


.IFF 
.ENDC 


.UORD 
.UORD 


POSTS 


000060 


000007 
000176 


. = 176 


.UORD 


ERL»G+<MMG»T*2>+<TI««IT*4> 


000176 


177550 


.IIF DF 


PC*CSR» 


.UORD PC*CSR 


000000 




.PSECT 


PCDyR 




000000 




PCSTRT! 
.IF NB 
.GLOBL 

.IFF 
.IF NB 


.UORD 

<> 


<-.>/2. -1 + "0100000 






.IIF NE 


%3 

.UORD 


.ERROR (ODD OR ILLEGAL VECTOR 
8"C3 






.IFF 










.IF DF 


PCtVTB 








.GLOBL 


PCtMTB 




000000 


100025 


.IFF 


.UORD 


<PC»VTB-.>/2. -1 + "0100000 






,IIF NE 


PCtVECSS .ERROR PC»VEC (ODD OR ILLEGAL VECTOR 








.UORD 


PC»VEC8"C3 






.ENDC 










.ENDC 










.ENDC 






000002 


000146 




. UORIi 


PCINT-. r"0340 


000004 


000340 








000006 




PCSYS! J 






000006 


000000 


PCLQEf! 


.UORD 





000010 


000000 


PCCOE! t 


.UORD 






(QUEUE HEADS 



I/O Initiation S(»ction 



5 000012 016704 
177772 
6 



hOV 



PCCQEiR4 



(POINT TO CURRENT QUEUE 
(ELEMENT 



For a character-oriented device, the word count must be shifted left to 
change it to a byte count (this is the same as multiplying it by 2). 
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7 


000016 


006364 
000006 




ASL 


Q*UCNT(R4) 


rCONVERT WORD COUNT TO 


8 












iBYTE COUNT 


9 


000022 


103410 




BCS 


PP 


!IF NEGATIVE. PUNCH (OR 


10 












J ERROR IN NO PUNCH) 


11 


000024 


001505 




BEQ 


PCDONE 


»A REQUEST FOR BYTES 


12 












SIS A SEEKr JUST EXIT 


13 


000026 


012705 
177550 




MOV 


*PC*CSR.R5 


(READ REQUESTf GET THE 


14 












SCSR 


15 


000032 


005725 




TST 


<R5) + 


J IS READER READY? 


16 


000034 


100064 




BPL 


PCGORIi 


iYESf START TRANSFER 


17 


000036 


052754 
020000 




BIS 


*E0F$Fe-(R4) 


JNOT READY ON ENTRY. 


18 












(SET EOF 


19 


000042 


000504 




BR 


PCFIN 


(AND COMPLETE OPERATION 


1 






i START 


PUNCH 


OPERATION (IMMEDIATE ERROR IF NO PUNCH 


2 
3 
4 






; SUPPORT) 






000044 




PP! 








5 






.IF EQ 


PRlltX 






6 


000044 


052737 
000100 
177554 




BIS 


*100,e*PP*CSR 


(CAUSES INTERRUPT. 


7 












(STARTING TRANSFER 


8 
9 


000052 


000207 




RTS 


PC 





Table for two vectors: 



10 

11 



( PUNCH-READER VECTOR TABLE 



The .DRVTB macro: 



12 000054 .DRVTB PC . PC*VEC . PCINT 

.IF NB PC 
000054 PCtVTBt; 

.IFF 

. = .-2 

.ENDC 
000054 000070 .WORD PC*VECS"C3t PCINT- .. 340 ! 0. 

000056 000072 
000060 000340 
000062 000000 

13 000064 .DRVTB .PP$VEC. PRINT 

.IF NB 

»vtb; ! 

.IFF 
000062' .=.-2 
.ENDC 
000062 000074 ,UORD PP$VECS"C3. PRINT- .. 340 ! . 

000064 000010 
000066 000340 
000070 000000 
14 



Punch interrupt Service Section 



15 
16 



( PUNCH INTERRUPT SERVICE 



The .DRAST macro: 
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17 000072 



.DRAST 
.GLOBL tlNPTR 
.IF B <PCIiONE> 

RTS 
.IFF 



PP,4.PCD0NE 



Z7 



The abort entry point: 





000072 
000074 


000462 
004577 


• ENDC 
PPINTtI 


BR 
! JSR 


PCDONE 
%5>(?*INPTR 








18 


000100 
000102 


000220 
000140 
016704 




.UORII 
MOV 


"C<4*"040>S"0340 
PCCQE>R4 


(POINT TO 


CURRENT QUEUI 


19 




177702 










SELEMENT 




20 


000106 


012705 




MOV 


*PP*CSRfR5 




fPOINT TO 


PUNCH STATUS 


21 




177554 










(REGISTER 





Bit 15 in PP$CSR is the error bit. The possible errors for paper tape include 
device out of tape, and tape jammed. 



22 


000112 


005725 




TST 


(R5) + 


(ERROR? 


23 


000114 


100411 




BMI 


PPERR 


(yesf punch out of paper 


24 






.IF EQ 


MMGtT 






25 








ADD 


*Q$UCNTrR4 


(POINT TO WORD COUNT 



The transfer is done if the required number of bytes is transferred without 
error. 



26 






TST 


eR4 


(ANY MORE CHARACTERS TO 


2 7 










(OUTPUT? 


28 






BEQ 


PCDONE 


(N0> TRANSFER DONE 


29 






INC 


eR4 


(DECREMENT BYTE COUNT 


30 










(<IT IS NEGATIVE) 


31 






MOVE 


e-(R4) r@R5 


(PUNCH CHARACTER 


32 






INC 


8R4 


(BUMP POINTER 


33 




.IFF 








34 


000116 


005764 
000006 


TST 


OtUCNT(R4) 


(ANY MORE CHARACTERS TO 


35 










(OUTPUT? 


36 


000122 


001446 


BEO 


PCDONE 


(NOt TRANSFER DONE 


37 


000124, 


005264 
000006 


INC 


QtWCNT(R4) 


(DECREMENT BYTE COUNT 



liB 



( (IT IS NEGATIVE) 



$GTBYT is a pointer to the monitor $GETBYT routine. 



39 000130 

40 

41 000134 
42 



004777 
000152 



tl261E 



JSR 



PC.etGTBYT 



MOVB (SP)+reR5 
.ENDC (EQ MMGtT 



(GET A BYTE FROM USER 

(BUFFER 
(PUNCH IT 



Return to the monitor: 



43 000136 000207 
44 



RTS 



PC 



Appendix A-43 



45 
Ah 



•ENDC »EQ PRlliX 



Character-oriented devices should check for disabling conditions, such as 
no power on device, or no tape in reader or punch, and set the hard error bit 
(bit 0) in the Channel Status Word. 

47 000140 052754 PPERR! BIS #HDERR« » 0- < R4 > JSET HARD ERROR BIT 

000001 

48 000144 000443 BR PCFIN (60 TO I/O COMPLETION 



Reader Interrupt Service Section 



i READER INTERRUPT SERVICE 



The .DRAST macro: 



Z 000146 



.DRAST 
.GLOBL »INPTR 
.IF B <PCDONE> 

RTS 
.IFF 



PCf4rPCD0NE 



%7 



The abort entry point: 





000146 


000434 


.ENCC 


BR 


PCDDNE 




000150 


004577 
000144 


PC I NT: 


! JSR 


%5)e»INPTR 




000154 


000140 




. UORD 


"C<4*"040>8 


4 


000156 


016704 




MOV 


PCCQEjR4 


5 
6 




177626 












.IF EQ 


MMG«T 




7 








ADD 


tQ«UCNTiR4 


8 






•ENDC i 


lEQ MMG»T 




9 


000162 


012705 
177550 




MOV 


♦PC»CSR.R5 


10 












11 


000166 


005725 




TST 


(R5) + 


12 


000170 


100411 




BMI 


PREOF 


13 












14 






.IF EQ 


MMGtT 




15 








MOVB 


eR5re-<R4) 


16 












17 








INC 


(R4) + 


18 








DEC 


0R4 


19 






.IFF 






20 


000172 


111546 




MOVB 


eR5f-(SP) 


21 


000174 


004777 
000110 




JSR 


PCrStPTBYT 


22 


000200 


005364 
000006 




DEC 


0tWCNT(R4> 


23 






.ENDC f 


EQ MMG*T 




24 
25 
26 


000204 


001415 




BEQ 


PCDONE 


000206 


052745 


pcoord: 


BIS 


*PINT.-<R5) 






000101 









•0340 



.'POINT TO CURRENT QUEUE 

(ELEMENT 

5 AT WORD COUNT 

SPOINT TO READER STATUS 

JREGISTER 

>ANY ERRORS? 

JYES. ZERO-FILL BUFFER 

XGIVE EOF NEXT TIME) 

(PUT CHARACTER INTO 
J BUFFER 

JBUMP BUFFER POINTER 
(DECREASE BYTE COUNT 

(GET A CHARACTER 

(MOVE IT TO USER'S BUFFER 

(DECREASE BYTE COUNT 



(IF ZEROr UE ARE DONE 
(WITH THIS READ REQUEST 
(ENABLE READER INTERRUPT. 

(GET A CHARACTER 



Return to the monitor: 
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23 000212 000207 

29 



RTS 



PC 



Stop the device if there are errors or if the end of tape is reached: 



30 


000214 


005045 


F'REOF.' 


CLR 


-<R5) 


31 












32 


000216 






.FORK 


PCFBLK 




000216 


004577 
000100 




JSR 


Z5f(?*FKPTR 




000222 


000050 




.UORIi 


PCFBLK - 



jrHSABLE READER 

INTERRUPTS 

^REQUEST SYSTEM PROCESS 



For character-oriented devices, it is necessary to clear the remainder of the 
user's buffer when end of file is reached (if CTRL/Z is typed on the console 
termhial, if there is no tape in the reader, and so on). The handler sets the 
EOF bit in the Channel Status Word the next time the handler is called to 
do a tiransfer. This convention iriakes character-oriented devices appear the 
same as random-access devices, and is in keeping with the RT-11 device in- 
dependence philosophy. 



33 


000224 




It! 






JCLEAR REMAINDER OF USER 


34 












(BUFFER 


35 






.IF EQ 


MH6$T 






36 








CLRB 


e-(R4) 


(CLEAR A BYTE 


37 








INC 


<R4) + 


(BUMP BUFFER ADDRESS 


38 








DEC 


eR4 


(COUNT DOWN BYTES 


39 












(REMAINING 


40 






.IFF 








41 


000224 


005046 




CLR 


- ( SP ) 


(SET NULL BYTE 


42 


000226 


004777 
000056 




JSR 


PC»e*PTBYT 


(PUT BYTE INTO USER 


43 












(BUFFER 


44 


000232 


005364 
000006 




DEC 


Q«UCNT(R4) 


(COUNT DOWN BYTES 


45 












(REMAINING 


46 






.ENDC i 


!EQ MMG$T 






47 


000236 


001372 




BNE 


1« 


(LOOP UNTIL DONE 



Branch here on abort also: 



46 000240 005037 PCDONE! CLR e*PC»CSR 

177550 
49 

50 .IF EQ PR11*X 

51 000244 005037 CLR e»PP*CSR 

177554 
52 

53 .ENDC (EQ PR11*X 

54 000250 005067 CLR PCFBLK+2 

000020 
55 



(TURN OFF THE READER 

(INTERRUPT 

(TURN OFF THE PUNCH 

(INTERRUPT 

(CLEAR FORK BLOCK TO 

(AVOID DISPATCH 



I/O Completion Section 



The .DRFIN macro: 



56 000254 PCFIN! .DRFIN PC 

.GLOBL PCCQE 

000254 010704 MOV X7tXA 

000256 062704 ADD ♦PCCQE-.fX4 
177532 



(GO TO I/O COMPLETION 
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0002(62 


013705 
000054 




MOV 


e*''054jX5 




000266 


000175 
000270 




JMP 


e''0270(5) 


57 












58 


000272 
000274 
000276 

000300 


000000 
000000 
000000 
000000 


PCFBLK} 


.WORD 


OiOf OrO 


59 













iPORK QUEUE BLOCK 



Handler Termination Section 



The .DREND macro: 



60 000302 






.DREND 


P 


000302 




.PSECT 


PCDVR 








.IIF NIiF PCtENIi 


r 1 






.IF EQ 


.-PC«END 


000302 




PCtENIi! 
.IF NE 


MHGtT 




000302 


000000 


»RLPTR{ 


! .WORD 





000304 


000000 


*MPPTR! 


: ,UORD 





000306 


000000 


tGTEYT! 


: .WORD 





000310 


000000 


tPTBYT: 


: .UORD 





000312 


000000 


»PTURD! 
.ENIiC 
.IF NE 


! .WORD 
ERL$6 





000314 


000000 


tELPTR! 
.ENtiC 
.IF NE 


! .WORD 
TIH»IT 





000316 


000000 


♦TIMIT! 
.ENBC 


: .WORD 





000320 


000000 


*INPTR! 


: .WORD 





000322 


000000 


SFKPTR! 
.6L0BL 


: . WORD 
PCSTRT 







000324 


PCEND = 
■ EN DC 


■= » 




61 










62 


000001 


.END 







PCtEND! 



SYMBOL TABLE 



EOF* = 


020000 




PCtVTE 


000054RG 


002 


Q.COMP= 


000014 




ERL*G = 


000001 




PINT = 


000101 




Q.CSU = 


000002 




FILST»= 


100000 




PP 


000044R 


002 


C1.ELGH= 


000024 




HDERRt= 


000001 




PPB 


177556 




Q.FUNC= 


000006 




HNDLR*= 


004000 




PPERR 


000140R 


002 


0, JNUM= 


000007 




hMGtT = 


000001 




PRINT 


000074RG 


002 


Q.LINK= 


000000 




PCB 


177552 G 




PP«CSR= 


177554 G 




Q.PAR = 


000016 




PCCQE 


000010R6 


002 


PPtVEC= 


000074 G 




Q.UNIT= 


000007 




PCDONE 


000240R 


002 


PREOF 


000214R 


002 


Q.WCNT= 


000012 




PCDSIZ= 


000000 




PRGO = 


000001 




RONLYt= 


040000 




PCEND = 


000324RG 


002 


PR11*X= 


000000 




SPECL*= 


010000 




PCFBLK 


000272R 


002 


Q«BLKN= 


000000 




SPFUNt= 


002000 




PCFIN 


000254R 


002 


G1*BUFF = 


000004 




TIM»IT= 


000001 




PC60RD 


000206R 


002 


QtCOMP= 


000010 




WONLY*= 


020000 




PCINT 


000150RG 


002 


Q*CSW = 


177776 




♦ELPTR 


000314RG 


002 


PCLQE 


000006RG 


002 


QtFUNC= 


000002 




*FKPTR 


000322R6 


002 


PCSTRT 


OOOOOORG 


002 


QtJNUM= 


000003 




♦GTBYT 


000306RG 


002 


POSTS = 


000007 




Q»LINK= 


177774 




♦INPTR 


000320R6 


002 


PCSYS 


000006RG 


002 


QtPAR = 


000012 




tMPPTR 


000304R6 


002 


PC*COD= 


000007 




Q»UNIT= 


000003 




tPTBYT 


000310R6 


002 


PCtCSR= 


177550 G 




Q*WCNT= 


000006 




♦PTWRD 


000312RG 


002 


PCtEND 


000302R6 


002 


Q.BLKN= 


000004 




♦RLPTR 


000302RG 


002 


PC*VEC= 


000070 G 




Q.BUFF= 


000010 




tTIMIT 


000316RG 


002 


. AES. 


000200 
000000 


000 
001 














PCDVR 


000324 


002 














ERRORS 


DETECTED! 


















VIRTUAL MEMORY USED! 10240 WORDS ( 39 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 73 PAGES 
!.PC/L:HE/L!TTM = CND,PC 



A-46 Appendix 



Appendix B 

Converting Device Handlers to V04 Format 



Handlers for data devices need no conversion to upgrade from V03 format 
to V04 format. If your system conditional file, SYCND.MAC, is the same 
for V03 and V04, you can use tlie .SYS handler files from V03 on the V04 
system without reassembling or relinking them. The conditional files are 
the same if you use the distributed monitors, or if you perform a system 
generation and select the same support for memory management 
(MMGr$T), error logging (ERL$G), and device time-out (TIM$IT). 

The device handler macros (.DElBEG, .DRAST, and so on) are completely 
upward-compatible. This means that you can reassemble a V03 handler on a 
running V04 system without altering the source file. However, DIGITAL 
recommends that you include t;he .DRDEF macro and modify the other 
handler macro calls to conform to the V04 format to ensure future com- 
patibility. 

If you have a V03 handler for a system device, you must upgrade the source 
beforei you use the handler with a V04 system. Use the .DRDEF macro to 
perform the preamble set-up for you. Conform to the V04 format for the rest 
of the! macro calls. You must include the .DRBOT macro and write a 
primary driver as well. For more information on writing a system device 
handler, see Section 7.10. In Appendix A, both the RK and DX handlers are 
for system devices; they both contain primary drivers. 

To create a system device handl(;r for a V03 system, it was necessary to edit 
SYCND.MAC to include the symbol $ddSYS = 1, and to assemble the 
handler with SYSDEV.MAC, wliich contained $SYSDV = 1. You need not 
perform either of these tasks when you create a V04 system device handler. 
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Appendix C 

Sample Application Program 



This appendix contains a listing of ADDISK.MAC, a foreground program 
that collects data from an A/D converter and stores it in a buffer. The pro- 
gram, which also writes the buffer contents to mass storage, contains an ex- 
ample of an in-Une interrupt service routine. ADDISK requires LPS 
hardware. 

Figure C-1: Sample Application Program 



ADDISK.MAC TEST ANALOG SAMPLER MACRO V04.00 
TABLE OF CONTENTS 



2-JAN-80 02:30!57 



1- 


8 


EQUATES Afi 


ID MCAl 


-LS 


1- 


57 


USR DATA 






;3-- 


1 


PROGRAM INITIALIZATION 


3- 


27 


SCAN INITIALIZATION 


3- 


4B 


START SAMPLING 




5- 


1 


SCAN COMPLETION 




7- 


1 


INTERRUPT 


SERVICE ROUTINE 


7- 


34 


INTERRUPT 


COMPLETION ROUTINE 


9- 


31 


PROGRAMME! 


1 REQUEST AREAS 


9- 


56 


TEMPORARY 


STORAGE AMD BUFFERS 


1 








.NLIST TTM 


2 








•NLIST CND 


3 








•TITLE ADDISK.MAC TEST ANALOG SAMPLER (LPS) 


4 

5 




} 




AN ANALOG SAMPLING PROGRAM - U.N-S. 


6 




r 




EDITED i MODIFIED 8/79 - L.C.P. 


7 
8 








.SBTTL EQUATES AND MCALLS 


9 
10 




f 




EQUATES SPECIFIC FOR THE RT-11 MONITOR 


11 
12 




000044 




JSU==44 ^ABSOLUTE LOCATION OF THE 


13 








fJOB STATUS UORD 


14 




000046 




USRPTR=46 fUSR POINTER LOCATION 


15 
.16 
17 
18 




i 




EQUATES SPECIFIC FOR LPS HARDWARE 




000360 




ADyEC=360 JVECTOR FOR A/D INTERRUPT 


19 




000006 




ADCPRI=6 ;a/D HARDWARE PRIORITY 


20 




000140 




ADVAL=140 iA/D START ON CLOCK 


21 




000417 




CLKVAL=417 J60 LPS CLOCK TICKS 


22 








;PER SECOND> 


23 








(REPEAT MODE i 60 BIT SET 


24 




177772 




BpyAL=-6. i* OF TICKS PER SAMPLE 


25 




170400 




ADSTAT=170400 fA/D STATUS REGISTER 


26 




170402 




ADDATA=170402 SA/D DATA REGISTER 


27 




170402 




LEDREG=ADDATA 5LED DISPLAY REGISTER 


28 




170404 




CLKREG=170404 JCLOCK STATUS REGISTER 


29 




170406 




BPREG=170406 (CLOCK BUFFER PRESET 


30 








(REGISTER 


31 










32 




i 




EQUATES SPECIFIC TO THE BUFFERING 


33 
34 
35 




J 




♦EDIT FOR CUSTOM CONFIGURATION* 




000004 




T0T1SUF = 4 (TOTAL BUFFERS PER "RUN" 


36 




000010 




eLKBUF=10 (MASS STORAGE BLOCKS PER 


37 








(BUFFER 
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Figure C-1: Sample Application Program (Cont.) 



38 




004000 




39 








40 








41 






•t 


42 








43 




000001 




44 




000002 




45 








46 




000004 




47 








48 




000010 




49 








50 








51 






1 


52 








53 








54 








55 








56 








H7 








5a 








59 






5 


60 






f 


61 






) 


62 








63 


000000 


075306 


DEVBLK 




000002 


003344 






000004 


035503 






000006 


014474 




64 








65 


000010 




earea: 



BUFSIZ=BLKBUF*400 



.'WORDS (SAHPLES) PER 
SBUFFER 



EQUATES SPECIFIC TO ERROR FLAGGING 



PRERR=1 
SYERR=2 



ADERR=4 
URERR=10 



(PROGRAMMED REQUEST ERROR 
JSYNCH ERROR. BUFFER 
(FILLED TOO SOON 
!A/D ERROR, SLOW 
(INTERRUPT SERVICE 
(WRITE ERROR, SLOW 
(BUFFER OUTPUT 



3 


000022 




4 






5 


000022 






000022 


012700 
001205 




000026 


104351 


6 


000030 


012737 
000022 
000046 


7 






e 


000036 






000036 


012700 
001150 




000042 


012710 
010001 




000046 


012760 
001102 
000002 




000054 


012760 
177775 
000004 




000062 


104375 


9 


000064 


016767 
001012 
001042 


10 






11 






12 






13 


000072 






000072 


012700 
001150 




000076 


012710 
014400 




000102 


012760 
000360 
000002 




000110 


104375 


14 






15 


000112 


103554 



MCALLS FOR PROGRAMMED REQUESTS AND MACROS 

.MCALL .PRINT, .EXIT, .TT YIN, .6TJB, .TTINR, ,SPND 
.MCALL .RSUM, .ENTER, . WRITE ,. PURGE , .WAIT,. CLOSE 
.MCALL .SYNCH, .DEVICE, .PROTECT, .INTEN,.QSET 

.SBTTL USR DATA 

THE USR DATA IS GROUPED HERE TO MAXIMIZE THE 
SPACE FOR SWAPPING BY THE USR AND MINIMIZE THE 
TOTAL FOREGROUND SPACE. 

.RAD50 /SYOADDISKDAT/ (USED BY .ENTER CALL 



iiLKU 5 (EMT ARG BLOCK FOR .ENTER 

.SBTTL PROGRAM INITIALIZATION 

USRSWP! (USR SWAP ADDRESS HERE... 

LPSST;! .PRINT *BGNMSG (START PROGRAM HERE 
MOV *BGNMSG,ZO 



EMT 
MOV 



-0351 

♦USRSWP, e*USRPTR (FILL IN USR SWAP 



.GTJB #AREA,*JBBLK 

MOV *AREA,%0 

MOV ♦16.*"0400+1, (0) 

MOV *JBBLK,2,(0) 



(ADDRESS FOR MONITOR 
(GET THE JOB INFORMATION 



MOV 



EMT 
MGV 



*-3,4. (0) 



"0375 
GJ0BN0,SJ0BN0 



(GIVE JOB ♦ TO .SYNCH 



PROTECT INTERRUPT VECTORS 

.PROTECT ♦AREA,#ADVEC (PROTECT A/D INTERRUPT 
MOV *AREA,ZO 

MOV *25.*"0400+0»(0) 

MOV ♦ADVEC,2.(0) 



EMT 
BCS 



"0375 
PROERR 



(VECTOR 

(BRANCH IF ERROR 
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16 


000114 


005037 
170400 


17 


000120 


012737 

000454' 

000360 


18 






19 


000126 


012737 
000340 
000362 


20 


000134 


005037 
170404 


21 






22 






23 






24 






25 


000140 






000140 


012700 
001150' 




000144 


012710 
006000 




000150 


012760 

001074' 

000002 




000156 


, 104375 


2 A 






27 






28 






29 


000160 




30 


000160 






000160 


012700 
000010' 




000164 


012710 
001000 




000170 


012760 

000000' 

000002 




000176 


012760 
000040 
000004 




000204 


104375 


31 






32 


000206 


103512 


33 


000210 


005067 
000746 


34 






35 






■3 6 






37 


000214 


012767 
004000 
000742 


38 


000222 


012767 
001776 
000744 


39 






40 


000230 


012767 
011776 
000734 


41 






42 






43 


000236 


016767 
000732 
000724 


44 






45 


000244 


012767 
000004 
000714 


46 






47 






48 






49 






50 






51 







CLR etADSTAT (MAKE SURE A/D IS OFF! 

MOV #AniNTfe*AIiVEC >SET UP INTERRUPT SERVICE 



^ADDRESS IN VECTOR 
MOV *340f l?*AtiVEC + 2 fAT PRIORITY 7 



CLR 



(?*CLKREG 



JMAKE SURE CLOCK IS OFF 



! THIS PROGRAMMED REQUEST GUARANTEES THAT THE A/D 

f WILL BE TURNED OFF WHEN WE EXIT THIS JOB... 

.DEVICE *AREAf*ADDEV 

MOV tAREAiZO 

MOV *12.*'~0400+0» (0) 

MOV #ADDEV»2.(0) 

EMT "0375 

.SBTTL SCAN INITIALIZATION 

scan: i START THE SCANNING HERE 

•ENTER ♦EAREA>*0f*DEVBLKr»EiLKBUF*TOTBUF fOPEN 

MOV tEAREAfXO 

MOV ♦0+<2.*"0400>r (0) 

MOV »DEVBLK»2. (0) 



MOV 



EMT 



BCS 
CLR 



#BLKBUF*T0TBUF»4. <0) 



"0375 

ENTERR 
BLOCK 



(DISK FILE 
(BRANCH IF ERROR 
(START AT BLOCK #0 



INITIALIZE THE BUFFER POINTERS AND COUNTERS 
MOV *BUFSI2>BUFCTR (SET UP SAMPLE COUNTER 

MOV *BUFA.LSTPTR (SET UP CURRENT BUFFER 



(POINTER 
MOV tBUFBrNXTPTR (SET UP NEXT BUFFER 



(POINTER (DOUBLE 
(BUFFERING) 
MOV LSTPTRfBUFPTR (A/D WILL START WITH 



(THIS BUFFER 
MOV *TOTBUFrBUFNO (INITIALIZE ♦ BUFFERS 



(IN RUN 
.SBTTL START SAMPLING 
START THE SAMPLING 
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52 000252 



53 

54 000260 



55 

56 000266 



012737 
000140 
170400 

012737 
177772 
170406 

012737 
000417 
170404 



HOV 



MOV 



♦ AIlVAL.etADSTAT fSET UP FOR A/D SAMPLING 



JON CLOCK OVERFLOW 
#BPVALje#BPREG fSET UP CLOCK PRESET 



(BUFFER 
MOV ♦CLKVALretCLKREG JSTART UP THE CLOCK ! ! ! 



3 
4 

5 000274 
000274 

000300 
6 
7 000302 

000302 

000306 

8 

9 
10 
11 
12 

13 000310 

14 000314 

15 000320 
000320 

000324 
16 

17 000326 

18 000332 
19 

20 
21 
22 000334 



23 000342 

24 000344 
000344 

000350 

25 000352 



26 000360 

27 000362 
000362 



000366 
28 
29 000370 



30 000376 

31 000400 
000400 



000404 



012700 

001256' 

104351 



012700 
000400 
104374 



005037 
170404 
005037 
170400 

012700 
003000 
104374 

105767 
000645 
001434 



132767 
000001 
000635 
001403 

012700 

001736' 

104351 

132767 

000010 

000617 

001403 

012700 

001521' 

104351 

132767 
000004 
000601 
001403 

012700 

001624' 

104351 



.SBTTL SCAN COMPLETION 

WAIT HERE UNTIL FULL SCAN COMPLETES 

J TELL USER WE'RE 



.PRINT 
MOV 



EMT 



• SPNIi 
MOV 



EMT 



tSMESG 
*SMESG>%0 

"0351 

*1*"0400.Z0 
"0374 



CLR 


etCLKREG 




CLR 


e*AtiSTAT 




.CLOSE 


♦ 




MOV 


*0+<6.*-0400; 


»X0 


EMT 


"0374 




TSTB 


ERROR 




BEQ 


EXITP 





fSUSPENDING. , . 
(SUSPEND UNTIL RESUME 



? ISSUED FROM 

S INTERRUPT SERVICE 

^ROUTINE 

iUHEN UE ARE AUAKENEDr 

fSTOP EVERYTHING ! 

5TURN OFF CLOCK.. , 

(TURN OFF A/D 

(CLOSE THE CHANNEL TO 



JSAVE THE DATA 
(ANY KIND OF ERROR? 



NO. 



.EXIT NORMALLY 



( PROCESS ANY ERRORS 
ERRPRO! BITE tPRERR. ERROR 



(HARD WRITE ERROR? 



BEB ERRWR iNO, TRY ANOTHER 

.PRINT tWRIMSO (REPORT DISK WRITE ERROR 
MOV tWRIMSGrXO 



ERRUR! 



EMT 
BITB 



"0351 
♦URERRfERROR 



(BUFFER OVERRUN? 



BEQ ERRAD (NO. TRY ANOTHER 

.PRINT tERRMSG (BUFFER OVERRUN, OUTPUT 
MOV *ERRMS6rZ0 



EMT 
ERRAD: BITB 



"0351 
tADERRr ERROR 



(TOO SLOW 
(A/D OVERRUN? 



BEQ ERRSY (NOi TRY ANOTHER 

.PRINT tADCMSG (A/D ERROR, SLOW 
MOV *ADCHSGfXO 



EMT 



-0351 



32 



(INTERRUPT SERVICE 
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33 


000406 


132767 
000002 
000563 


ERRSY! 


BITB 


♦SYERRr ERROR 


i .SYNCH ERROR? 


34 


000414 


001403 




BEQ 


EXITP 


;N0, go EXIT 


35 


000416 






.PRINT 


#SYNMSG f. SYNCH 


ERRORf BUFFER 




000416 


012700 
001557' 




MOV 


♦SYNMSGjXO. 






000422 


104351 




EMT 


"0351 




36 












JFILLED TOO SOON 


37 














38 


000424 




EXITPJ 


.PRINT 


♦ EXTMS6 J REPORT 


EXITING PROGRAM 




000424 


012700 
001414' 




MO!V 


♦EXTMSGtXO 






000430 


104351 




EhT 


"0351 




39 


000432 






.EXIT 




(EXIT TO RT-11 




000432 


104350 




EhT 


"0350 




40 














41 
42 
43 






r 


FATAL ERRORS HERE. . . 




000434 




ENTERRi 


.PRINT 


♦ENTMSG J.ENTER 


ERRORr FATAL! 




000434 


012700 
001677' 




MOW 


♦ENTMSGfXO 






000440 


104351 




EMIT 


"0351 




44 


000442 






.EXIT 




(EXIT IMMEDIATELY 




000442 


104350 




EMT 


"0350 




45 


000444 




proerr: 


.PRINT 


♦PROMSG (.PROTECT ERROR, FATAL! 




000444 


012700 
001460' 




MOV 


♦PROMSGrZO 






000450 


104351 




EMT 


"0351 




46 


000452 






.EXIT 




(EXIT IMMEDIATELY 




000452 


104350 




EMT 


"0350 





000454 
000454 



000460 



7 000462 



9 000466 
10 000470 



11 

12 000476 



13 000504 



14 

15 000510 



16 000516 

17 

18 000522 

19 

20 000524 

21 

23 
24 
25 
26 000526 



004577 
000054 
000040 

005737 
170400 

100003 
152767 
000004 
000501 

013777 
170402 
000464 
004767 
000272 

062767 
000002 
000452 
005367 
000442 

001422 

000207 



152767 
000002 
000443 



AD I NT.' 



.SBTTL INTERRUPT SERVICE ROUTINE 
A/D INTERRUPT ROUTINE 



.IiNTEN 
J SIR 



.UIORD 

TST 



BPL 
BISB 



NOADER! MOy 

CALL 

ADD 

DEC 

BEQ 
RTS 



ADCPRI 
5.f8"054 



(ALERT RT-11 AND DROP 



"C<ADCPRI«32.>»224. 

(PRIORITY TO THAT OF HDWE 
etADSTAT (INTERRUPT SERVICE TOO 



NOADER 
♦ADERRfERROR 



(LATE? 

(BRANCH IF OK... 

(SET A/D ERROR BITf 



(BUT CONTINUE 
e*ADDATA,eBUFPTR (STORE SAMPLE IN BUFFER 



LEDDIS 

♦2rBUFPTR 

BUFCTR 

BUFFUL 
PC 



(DISPLAY A/D VALUE IN 

(LED DISPLAY 

(INCREMENT BUFFER POINTER 



(DECREMENT COUNT... THRU 

(UITH BUFFER? 
(BRANCH IF YES 
(<BUFFER FULL) 
(OTHERWISE, JUST RETURN 
(FROM INTERRUPT 



THIS CODE IS REACHED IF .SYNCH FAILS 
<2ND BUFFER FILLED TOO FAST !?!) 



SYNERR! BISB 



♦SYERR, ERROR 



(SET .SYNCH ERROR BIT 
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28 


000534 


005037 
170404 


29 


000540 


005037 
170400 


30 


000544 


012767 
000001 
000412 


31 






32 


000552 


012737 
000140 
170400 


33 


000560 


012737 
000417 
170404 


34 


000566 


000207 


35 






36 






37 




i 


38 




J 


39 




5 


40 




i 


41 




f 


42 






43 


000570 


012767 BUFFUL 

004000 

000366 


44 


000576 


156767 
000374 
000373 


45 






46 






47 






48 


000604 


016767 
000362 
000356 


49 






50 


000612 


016767 
000356 
000352 


51 


000620 


016767 
000344 
000346 


52 






53 






54 






55 






56 






57 






58 


000626 






000626 


012704 MOV 
001132 




000632 


013705 
000054 




000636 


004575 
000324 


59 






60 


000642 


000731 


61 






62 


000644 


105767 
000327 


63 






64 


000650 


001044 


65 


000652 


152767 
000010 
000316 


66 






67 


000660 






000660 


005000 




000662 


104374 


68 






69 


000664 


103442 



(THEN STOP INTERRUPTS! 
SSTOP THE CLOCK. . . 

jANIi THE A/D. . . 

(TRY .SYNCH AGAIN ON 



SNEXT INTERRUPT 
MOy *ADVALre#AriSTAT (START UP THE A/D AGAIN... 



CLR 


etCLKREG 


CLR 


etADSTAT 


MOV 


♦IfBUFCTR 



HOV 



RTS 



♦CLKVALfBtCLKREG (ANIi THE CLOCK.. 



PC 



(RETURN AND HOPE FOR 
(BETTER! 



THIS CODE PROCESSES THE BUFFER. IT FIRST ADJUSTS 
THE POINTERS AT PRIORITY OF THE LPS HARDWARE, 
THEN ISSUES A .SYNCH AND URITES THE BUFFER TO 
MASS STORAGE, (THIS CODE RUNS AS AN INTERRUPT 
COMPLETION ROUTINE AT PRIORITY LEVEL 0). 



MOV 



BISB 



MOV 



♦BUFSIZtBUFCTR (RESET THE BUFFER COUNTER 



UFL AG, ERROR 



NXTPTRjBUFPTR 



(SET A 'WRITE-IN-PROGRESS* 



(FLAG 

( (WILL BE DOWN UNLESS 
>WRITE IS UNFINISHED) 
(FLIP-FLOP THE BUFFER 



(POINTERS 
MOV LSTPTR,NXTPTR (THIS FOR NEXT TIME. 



MOV 



BUFPTRrLSTPTR (THIS FOR TIME AFTER 



(NEXT. 
.SBTTL INTERRUPT COMPLETION ROUTINE 
NOW IT IS SAFE TO ALLOW INTERRUPTS... 

(ALLOW PROG REO 8 QUEUE 



.SYNCH 
*ASYN, 


♦ ASYN 
Z4 


MOV 


e*-054,Z5 


JSR 


5. ,8-0324(5.) 


BR 


SYNERR 


TSTB 


ERROR 


BNE 
BISB 


ERRET 
#URERR,UFLA6 


.WAIT 

CLR 

EMT 


*0 
XO 
"0374 


BCS 


WRIERR 



(COMPLETION RTNE 
(ERROR RETURN . ., SYNCH 
(FAILED - GO PROCESS 
(NORMAL RETURN. . . ANY 

(KIND OF ERROR LATELY? 
(YES, LEAVE IMMEDIATELY! 
(SET FLAG WHILE WE'RE 



(WRITING TO DISK! 

(MAKE CERTAIN LAST .WRITE 



(FINISHED OK 
(BRANCH IF IT DIDN'T 
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70 000666 
000666 

000672 

000676 

000704 

000712 

000720 



000726 
71 

72 000730 

73 000732 
000732 

000736 
74 
75 000740 



76 

77 000746 



78 000754 

79 

80 000760 
81 

82 000762 
000762 

000766 
83 
84 000770 

85 



012700 
OOllSO 
012710 
004400 
016760 
000260 
000002 
016760 
000262 
000004 
012760 
004000 
000006 
012760 
000001 
000010 
104375 

103420 

012700 
001365 
104351 

142767 
000010 
000230 

062767 
000010 
000206 
005367 
000206 

001003 



012700 
001000 
104374 



ERRET! 



.URXTE *AREAftOfNXTPTR>*BUFSIZ, BLOCK JOUTPUT 

MOV tAREAiZO 

MOV ♦0+<9.*"0400>f(0) 

NOV BLOCKr2.<0) 

MOV NXTPTR»4. (0) 



MOV 



MOV 



EMT 



DEC 



BNE 



000207 COMRET! 



EMT 
RTS 



*BUFSIZf6. (0) 



*1»8. (0) 



0375 



BCS 


URIERR 




.PRICNT 


♦BUFUR 




MOV 


♦BUFWRi 


XO 


EMT 


"0351 




BICE) 


tURERR. 


WFLAG 



JBUFFER TO DISK 
i BRANCH IF ERROR 
(LET USER KNOW WE'RE 



SALIVE i WELL,.. 
JOUTPUT DONEf FLAG 



(BACK DOWN 
ADD #BLKBUF, BLOCK ^UPDATE BLOCK POINTER.., 



BUFNO 



COMRET 



.RSUM 

MOV »2.*~0400fZ0 



"0374 
PC 



jpone with a buffer r are 

jwe thru with scan? 
;no...just return if more 

iBUFFERS IN SCAN 
(ERRORS, OR DONE . . . 



fAWAKEN MAINLINE 

r RETURN FROM INTERRUPT 

tVIA RMON 



1 
?. 
3 
4 000772 



5 001000 

6 

-/ 

a 

9 001002 



10 

11 001010 



12 001014 



13 

14 001022 



15 

16 001030 



152767 
000001 
000177 
000770 



012767 
000005 
000174 

005067 
000164 
017767 
000150 
000160 

116767 
000154 
000150 

142767 
000370 
000142 



EXIT HERE ON WRITE ERROR 
WRIERR! BIS£i ♦PRERR, ERROR (FLAG A .WRITE ERROR... 

BR ERRET iAND TAKE ERROR RETURN 

mSPLAY DATA IN LPS L.E.D. DISPLAY... 

LEnnis: mov »5fLEDCT jset * of digits to 



CLR 
MOV 



LEDNX; MOVE 



(DISPLAY 
LEDTMP (CLEAR THE WORK SPACE 

BBUFPTR.ADTEMP (GET THE CURRENT 



(A/D VALUE 
ADTEMP. LEDTMP (GET WHAT'S LEFT OF 



BICB *370. LEDTMP 



(A/D VALUE 

(STRIP OFF ALL BUT 
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17 

18 001036 



19 001044 



20 

21 001050 



22 001054 



23 001060 



24 

25 001064 



27 001070 

28 001072 
29 

20 

31 

32 

33 

34 

35 

36 001074 

37 

38 001076 

39 001100 
40 

41 

42 001102 

43 001102 
44 

45 001132 

46 001134 
47 

46 001136 

49 001140 

50 001142 
001144 
001146 

51 
52 

53 001150 
54 
55 
56 
57 
58 
59 

60 001162 
61 

62 001164 
63 

64 001166 
001170 



61 

66 

67 001172 

68 

69 001174 

70 001176 
71 

72 001177 

73 

74 001200 

75 

76 001202 

77 001204 
78 



016737 
000136 
170402 
006267 
000132 

006267 
000126 
006267 
000122 
105267 
000115 

105367 
000114 

001354 
000207 



000000 

000000 



000000 
000000 



SLOWEST OCTftL DIGIT 
MOV l.EDTMP.B#LEDRE6 (PUT INTO L.E.D. REGISTER 

(SHIFT 'REMAINIiER- 

(RIGHT 3 TIMES 
(TO RIGHT JUSTIFY 

(THE NEXT DIGIT. . . 

(TELL L.E.D. REGISTER 

(MHAT NEXT DIGIT IS 
(DECREMENT DIGIT COUNTER 

(. . .ARE UE THRU? 
(LOOP IF NOT 
(UE'RE DONE 
(. . .RETURN TO CALLER 



170400 ADDEV: 



000000 
000000 



jbblk: 

GJOBNO! 

000000 asyn: 

000000 SJOBNO! 

000000 
000000 
000000 
177777 
000000 



area; 



block: 

bufctr: 



000000 NXTPTR! 



000000 
000 



000 
000000 



000000 
000 



ASR 


ADTEMP 


ASR 


ADTEMP 


ASR 


ADTEMP 


INCH 


LEDTMP+1 



DECB 



BNE 
RETURN 



LEDCT 



LEDNX 



.SBTTL PROGRAMMED REQUEST AREAS 

THESE AREAS AND DATA BLOCKS ARE USED BY THE 
VARIOUS PROGRAMMED REQUESTS... 



.UORD 



.UORD 
.UORD 



.BLKU 

.UORD 
.UORD 

.UORD 
. UORD 
.UORD 



ADSTAT 








Of-1.0 



(.DEVICE LIST - A/D 
(STATUS REGISTER 
(LOAD UITH (STOP A/D) 
(STOP THE LIST OF 
(THINGS TO STOP! 

(ARG BLOCK FDR .GTJB 

(FILLED UITH JOB DATA 

(<12 UDS FOR V4) 

(ARG BLOCK FOR THE .SYNCH 

(FILLED AFTER THE 

( .GTJB CALL 



(REQUIRED VALUES FOR 



iRT-11 ! I ! 



(EMT ARG BLOCK FOR 
(VARIOUS PROG REQUESTS 



.BLKU 5 

.SBTTL TEMPORARY STORAGE AND BUFFERS 



MISCELLANEOUS STUFF. 
.UORD 
.UORD 



BUFNO! 

bufptr: 



lstptr: 

UFLAG! 



.UORD 
.UORD 



.UORD 



.WORD 
.BYTE 



error: .byte 

LEDTMP: .UORD 

adtemp; .uord 

ledct: .byte 



(BLOCK POINTER FOR 

(DISK WRITES. . . 

(SAMPLES LEFT TO PUT 

(IN BUFFER. . . 

(♦ BUFFERS LEFT IN SCAN... 

(POINTER UITHIN BUFFER 

(BEING FILLED. . . 

(POINTER TO BUFFER 

(BEING WRITTEN. . . 

(POINTER TO OTHER BUFFER.. 

(WRITE FLAG ... =1 IF 

( .WRITE IN PROGRESS 

(ERROR STATUS WORD 

((BIT MASK) 

(L.E.D. DISPLAY WORKING 

(SPACE 

( (DITTO) 

(* OF L.E.D. DIGITS TO 

(DISPLAY (COUNTER) 
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3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 



1205 
1256 
1322 
1365 
1414 
1460 
1521 
1557 
1624 
1677 
1736 



1776 
1776 



bgnhsg; 

SMESGt 

bufur: 

KXTMS6: 
F'ROMSG! 
EK'RMSG! 
SYNHSD! 

adcmsg; 

ENTMS6! 

urimsg: 



000022' 



t 

.NLIST 
.ASCI2 
.ASCII 
.ASCIZ 
.ASCIZ 
, ASCIZ 
•ASCIZ 
, ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
•ASCIZ 
.EVEN 

BUFA! 
BUFB! 



MESSAGE TEXT. • . 



BIN 



X*** A/D SAMPLING DEMO (LP'S HARDWARE) ***Z 

/SAMPLING STARTS » MAINLINE SUSPENnS/<12><15> 

/<THIS DEMO TAKES ABOUT IS MINUTES>/ 

/BUFFER XFERRED TO DISK/ 

7.*** A/D SAMPLING DEMO COMPLETED ***X 

/? .PROTECT ERROR - DEMO ABORTED!/ 

/? BUFFER OVERRUN r SLOW OUTPUT/ 

/? .SYNCH ERRORj SLOW SYNCH SERVICING/ 

X? A/D TIMING ERRORr SLOW INTERRUPT SERVICED 

/? .ENTER ERROR - DEMO ABORTED!/ 

/? .WRITE ERROR - DEMO ABORTED!/ 



.LIST BIN 

.ELKW BUFSIZ 

.BLKW BUFSIZ 

.END LPSST 



r BUFFER 'A" 
JBUFFER "B" 
!END OF SOURCE CODE 



SYMBOL TABLE 



ADCMS6 


001624R 


BUFWR 


001365R 


LEDTMP 


001200R 


ADCPRI= 


000006 


CLKREG- 


170404 


LPSST 


000022RG 


ADriATA = 


170402 


CLKVAL= 


000417 


LSTPTR 


001174R 


ADDEV 


001074R 


COMRET 


000770R 


NOADER 


000476R 


ADERR = 


000004 


DEVBLK 


OOOOOOR 


NXTPTR 


001172R 


ADINT 


000454R 


EAREA 


OOOOIOR 


PRERR = 


000001 


ADSTAT= 


170400 


ENTERR 


000434R 


PROERR 


000444R 


ADTEMP 


001202R 


ENTMSG 


001677R 


PROMSG 


001460R 


ADVAL = 


000140 


ERRAD 


000370R 


SCAN 


000160R 


ADVEC = 


000360 


ERRET 


000762R 


SJOBNO 


001134R 


AREA 


001150R 


ERRMSe 


001521R 


SMES6 


001256R 


ASYN 


001132R 


ERROR 


001177R 


SYERR = 


000002 


EGNMSG 


001205R 


ERRPRO 


000334R 


SYNERR 


000526R 


BLKBUF= 


000010 


ERRSY 


000406R 


SYNMSG 


001557R 


BLOCK 


001162R 


ERRWR 


000352R 


TOTBUF= 


000004 


EPREI3 = 


170406 


EXITP 


000424R 


USRPTR= 


000046 


BPVAL = 


177772 


EXTMSG 


001414R 


USRSWP 


000022R 


BUFA 


001776R 


GJOBNO 


001102R 


UFLAG 


001176R 


BUFB 


011776R 


JBBLK 


001102R 


WRERR = 


000010 


BUFCTR 


001164R 


JSW 


000044 


WRIERR 


000772R 


BUFFUL 


000570R 


LEDCT 


001204R 


URIMSG 


001736R 


BUFNO 


001166R 


LEDDI3 


001002R 


. . .VI = 


000003 


BUFPTR 


001170R 


LEDNX 


001022R 


. . .V2 = 


000027 


i;iUFSJ[Z = 


004000 


LEDREG= 


170402 






. ABS. 


000000 000 
021776 001 








ERRORS 1 


IIETECTED! 











VIRTUAL MEMORY USED! 10496 WORDS ( 41 PAGES) 
DYNAMIC MEMORY AVAILABLE FOR 36 PAGES 
jV4:ADDISK/L!MEB/L!TTM=V4!ADDISK 
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Abort entry points, 7-14, 7-15 
Aborting a job, 3-7 
Absolute binary file format, 8-28 
Absolute Loader, 8-28 
Acknowledgment block, 

QUEUE, 3-45 
Active Page Regicster, See APR. 
Adding a device to the error 

logger, 7-37 
Adding a device to the monitor 

tables, 3-65 
Adding an element to the I/O 

queue, 3-14 
Adding special functions to a 

device handler, 7-39 
Address, 

next free, 4-38 

physical, 4-2 

virtual, 4-2 
Address conversion, 

16-bit to 18-bit, 4-14 

XM, 4-9 
Address space, 

logical, 4-25 
Addressing , 

16-bit, 4-1 

18-bit, 4-3 
Advantages of device handlers, 

6-6 
Allocating memory, 2-19, 2-21 
Allocating queue elements, 3-12 
ANSI magtape labels (table), 9-23 
ANSI magtape standard, 9-22 
Application, 

debugging a multi-terminal, 5-29 

debugging an XM, 4-69 
Application program, 

sample, C-1 
Applications, 

device time-out, 7-31 

multi-terminal, 5-10 

planning XM, 4-49 

XM, 4-34 
APR, 4-11 

correspondence with virtual 
address (table), 4-56 
Arrays in extended memory, 4-35 
ASCII file format, 8-34 
ASEMBL, 1-2 
Assembling device handlers, 7-57, 

A-1 
Assigning job priority, 3-37 
AST word, 5-2, 5-19 
AST word (table), 5-19 
Asynchronous directory operation 
example, 10-10 



Asynchronous I/O, 3-12 
Asynchronous terminal status 

word. See AST word. 
Attaching a terminal, 5-20 
AVAIL, 3-13 

Available queue elements, 3-13 
Available queue elements 

(figure) , 3-14 



B 

Background console, 5-4 
Background job, 2-14 

loading, 2-15 

privileged, 4-31, 4-43 

privileged (figure), 4-31 

USR swapping considerations 
for, 2-36 

virtual, 4-27, 4-45 

virtual (figure) , 4-28 
Background job (figure) , 2-15 
Bad block replacement, 7-40, 

10-35 
Bad block replacement (table) , 

10-38 
Bad blocks, 

DECtape II, 10-40 
Baud rate, 

total allowable, 5-28 
BELL 103A-type modem, 5-28 
Binary blocks, 

formatted, 8-4 
16-bit addressing, 4-1 
18-bit addressing, 4-3 
Bitmap, 

low-memory, 2-1, 3-52 

low-memory (table) , 3-53 
BLKEY, 2-29 

Block-replaceable devices, 9-1 
Blocking a job, 3-31 
Blocking bits, 3-20, 3-59 
Blocking bits (table), 3-30, 3-59 
Blocking conditions, 3-23, 3-29 
Blocking conditions (table) , 3-30 
Blocks , 

contiguous, 9-8 
Boot-time console, 5-4 
Bootable magtape, 9-23 
Bootstrap, 7-50 

writing software, 7-52 
Bootstrap and DUP, 7-53 
Bootstrap error routine, 7-52 
Bootstrap Loader, 8-28 
Bootstrap read routine, 7-52 
BPT instruction, 4-68 
Buffers in extended memory, 4-35 
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Calling the error logger, 7-36 

Cancelling a timer element, 7-30 

Card codes, 10-31 

Card reader handler, 6-17, 10-30 

Carrier, 5-20, 5-26 

Cassette EOF detection, 10-28 

Cassette file header format, 9-26 

Cassette format (figure) , 9-25 

Cassette handler, 10-24 

Cassette handler functions, 10-25 

Cassette special functions, 10-27 

Cassette structure, 9-24 

CCB, 2-15 

Chain area, 2-7 

..CHAIN programmed request, 2-16 

Chaining (figure), 4-4 

Chaining to CREF, 8-35 

Changing keyboard commands, 

2-38 
Changing the I/O queue, 3-21 
Channel area (figure), 3-62 
Channel format, 

I/O (figure) , 3-52 
Channel Status Word, See CSW. 
Character devices, 7-44 
Characteristics, 

system job, 3-36 
Characteristics of a runnable 

job, 3-33 
Characters, 
control, 3-6 
fill, 2-4 
obtaining, 5-22 
printing, 5-22 
CHKEY, 2-29 
CHNWT$, 3-30 
Circumventing address 

limitations, 4-4 
Clock, 3-9 

pseudo, 3-11 
Clock support, 3-9 
Command console. 

See Background console. 
Command expansion buffer area, 

2-37 
Command files, 
indirect. 

See Indirect command files. 
Command String Interpreter, 

See CSI. 
Communicating with foreground 

jobs, 3-8 
Communicating with system jobs, 

3-8, 3-40 
Comparison of device handler and 
in-line interrupt service 
routine, 6-4 
Comparison of virtual and 

privileged jobs (table) , 4-33 



Compiler, 

writing a, 8-2 
Completing an I/O request, 3-22 
Completion queue, 3-17 

.SYNCH considerations for, 3-18 
SJ considerations for, 3-18 
Completion queue element, 3-18 
Completion queue element 
(figure) , 3-18, 3-60 
Completion routines, 3-11, 3-17, 

3-23 
Completion routines and the 

scheduler, 3-33 
Completion routines in SJ , 3-18 
Components of a multi-terminal 

system, 5-1 
Components of the queued I/O 

system, 3-11 
Components of the queued I/O 

system (figure) , 3-12 
Condition codes, 

PS, 7-11 
Conditionals, 

system generation, 7-4 
C0NFG2 (table) , 3-54 
C0NFG2 word, 3-54 
CONFIG (table) , 3-51 
CONFIG word, 3-51 
Configuration, 

terminal, 5-3 
Configuration word, 3-51 
extension, 3-5'' 
extension (table) , 3-54 
Configuration word (table) , 

3-51 
Considerations for USR swapping, 

2-30 
Console, 5-5 

background, 5-4 
boot-time, 5-4 
command , 

See Background console, 
moving the, 5-4 
private, 5-5 
shared, 5-5 
Console as special case, 5-25 
Console terminal, 5-4 

switching, 5-8 
Console terminal handler, 10-34 
Context, 

job's, 3-23 
Context switch, 

information saved during, 3-29 
Context switching, 3-23, 3-28 
Context switching in XM, 4-32 
Contiguous blocks, 9-8 
Control characters. 
See Characters. 
Converting a 16-bit to an 18-bit 
address, 4-14 
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Converting deivi 

format, B-1 

Core control bl 

Corrupted direc 

recovering da 
CR device handl 
.CRAW programme 
Creating a regi 
Creating a wind 
Creating system 

7-51 
CREF, 

chaining to, 
CREF file forma 
Cross-reference 

See CREF. 
.CRRG programme 
CSI, 2-27, 3-6 
CSW, 3-61 
CSW (table) , 3- 
.CTIMIO macro, 
CTRL/B, 3-8 
CTRL/C, 3-7 
CTRL/F, 3-8 
CTRL/0, 3-7 

resetting, 
CTRL/Q, 3-7 
CTRL/S, 3-7 
CTRL/X, 3-8, 3- 
CTS-300, 5-10 
Current cursor 

obtaining, 3- 
Data blocks, 

RT-11, 8-4 
Data set, 5-26 
Data structures 

multi-terraina 

RMON, 3-47 

XM, 4-51 



ce handlers to V4 

ock. See CCB. 
tory, 

ta from, 9-15 
er, 10-30 
d request, 4-61 
on, 4-61 
ow, 4-61 
device handlers. 



8-35 
t, 8-35 
file format, 

d request, 4-61 



63 
7-30 



5-23 



40 



position, 
8 



1, 5-1, 5-11 



Data transfer, 

starting, 7-12 
Data transfer errors, 7-15 
DCL, 

See DIGITAL Command Language. 
DD device handler, 10-39 
dd$COD, 7-4 
dd$CSR, 7-4 
dd$VEC, 7-4 
ddCQE, 3-13 
ddDSIZ, 7-4 
ddINT, 7-10, 7-13 
ddLQE, 3-13 
ddSTS, 7-7 

Debugging a device handler, 7-65 
Debugging multi-terminal 

applications, 5-29 



Debugging XM applications, 4-69 
DEC 026/DEC 029 card codes, 

10-31 
Decision subroutine 
DECtape II bad bloc 
DECtape II device h 
DECtape II format. 
Default mapping, 4- 
Default mapping (fi 
Deposit keyboard cc 
Design implications, 

XM, 4-66 
Designing a system job, 3-37 
Detaching a terminal, 5-23 
Determining sizes of components, 

2-39 
DEV macro. 7-60 



De 

2-39 
DEV macro. 
Device driver. 



7-60 
Device handler, 



See Device handler. 
Device handler, 
card reader, 6-17 
console terminal, 10-34 
CR, 10-30 
DD, 10-39 
DECtape II, 10-39 
DL, 10-37 
DM, 10-35 
DX, 10-29 
DY, 10-29 
GT, 2-19 
LS, 5-6 

MQ, 3-39, 6-22 
NL, 10-39 
PC, 10-34 
PP, 1-2 
PR, 1-2 

RLOl/02, 10-37 
system, 7-50 
TT, 3-1 

Device handler listing, 
DX, A-19 
PC, A-38 
RK, A-1 

Device handler macro, 

•DRAST, 7-14 

.DRBEG, 7-9 

.DRBOT, 7-53 

.DRDEF, 7-3 

•DREND, 7-18 

.DRFIN, 7-18 

.DRSET, 7-24 

.DRVTB, 7-10 
Device handler 
header, 7-9 



section, 
7-16 



neaaer, /-y 
I/O completion, 7-16 
I/O initiation, 7-11 
interrupt service, 7-13 
preamble, 7-3 
termination, 7-18 
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Device handlers, 2-19, 3-22, 6-4 

abort entry point, 7-14 

advantages of, 6-6 

assembling, 7-57, A-1 

block 0, 7-9 

cassette, 10-24 

cassette functions, 10-25 

converting to V4 format, B-1 

creating system, 7-51 

debugging with ODT, 7-66 

first five words, 7-9 

how to write, 7-1 

in XM, 7-41 

in XM (figure) , 7-43 

installing, 7-58 

installing magtape, 7-65 

linking, 7-58 

loading, 2-19, 2-22 

mapping to user buffer, 7-47 

mapping to user buffer 
(figure) , 7-49 

multi-vector, 7-10 

planning to write, 7-1 

size of, 2-39 

skeleton outline, 7-19 

special functions, 7-38 

specifics, 10-1 

structure of, 7-3 

suffix, 3-51 

system, 2-11 

system (figure), 2-12 

testing and debugging, 7-65 
Device handlers that access the 

user buffer, 7-47 
Device handlers that queue 

internally, 7-20 
Device I/O page. See I/O page. 
Device I/O time-out, 7-28 
•DEVICE macro, 6-12 
Device priority, 6-3 
Device size word, 7-8 
Device status word, 7-7 
Device status word (table), 

7-7 
Device tables, 3-62 

adding a device to, 3-65 
Device time-out applications, 

7-31 
Device vectors. See Vectors. 
Device-dependent information, 

10-1 
Device-identifier byte, 7-6 
Device-identifier byte (table), 

7-6 
Devices, 

block-replaceable, 9-1 

file-structured, 9-1 

information about, 6-8 

programming for specific, 10-1 

pseudo, 7-19 



Devices, (Cont.) 
random-access, 9-1 
sequential-access, 9-1, 9-22 
Devices that do not interrupt, 

7-19 
Differences between foreground 

and background jobs, 2-21 
Differences between virtual and 

privileged jobs, 4-32 
DIGITAL Command Language, 1-2, 

See Also Keyboard commands. 
Directory, 

recovering data from corrupted, 
9-15 
Directory caching, 
inhibiting, 2-29 
Directory date format (figure) , 

9-7 
Directory entries, 9-5 
Directory entry format, 9-5 
Directory entry format (figure) , 

9-5 
Directory example, 

asynchronous operation, 10-10 
Directory header format, 9-4 
Directory header words (table) , 

9-4 
Directory link words, 9-15 
Directory segment, 
sample (figure) , 9-9 
splitting, 9-13 
splitting (figure), 9-16 
Directory status word format, 9-5 
Directory status word format 

(figure) , 9-5 
Directory status word values 

(table) , 9-6 
Directory structure, 9-2 
Directory words, 

extra, 9-7 
Discarding terminal output, 3-7 
Diskette handlers, 10-29 
Diskette silo, 6-2 
DL device handler, 10-37 
DL interface, 

time-out routine for, 5-27 
DL-type interface, 5-2 
DLll-J interface, 5-28 
DLll-W interface, 5-28 
DM device handler, 10-35 
DM handler special functions, 

10-36 
DMA devices, 7-44 
Documentation on memory 

management hardware, 4-7 
Down-line loading, 8-28 
.DRAST device handler macro, 7-14 
.DRBEG device handler macro, 7-9 
.DRBOT device handler macro, 7-53 
.DRDEF device handler macro, 7-3 
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.DREND device handler macro, 7-18 
.DRFIN device handler macro, 7-18 
Driver, 

primary, 7-51 
Drivers, See Device handlers. 
.DRSET device handler macro, 7-24 
.DRVTB device handler macro, 7-10 
DUP and bootstrap, 7-53 
$DVREC table, 3-64 
DVREC$ p-sect, 2-14 
$DVSIZ table, 3-64 
Dwight D. Eisenhower, 1-3 
DX device handler, 10-29 
DX device handler listing, A-19 
DY device handler, 10-29 
Dynamic regions, 4-24 
Dynamic windows, 4-25 
DZ interface, 

polling routine for, 5-27 
DZ-type interface, 5-2 



Editor, 

K52, 1-3 

KED, 1-3 

TECO, 1-2 
EIS, 4-7 
Eisenhower, 

Dwight D. , 1-3 
EL, 3-35 

.ELAW programmed request, 4-64 
ELBLDR macro, 7-37 
Eliminating a region, 4-64 
Eliminating a window, 4-64 
.ELRG prograitimed request, 4-64 
Empty entry, 9-6 
Empty file. See Empty entry. 
EMT error codes, 2-4 
Enabling the high-speed ring 

buffer, 3-6 
$ENSYS (table), 3-27 
$ENSYS and the job's stack, 3-27 
$ENSys monitor routine, 3-27 
Entry, 

empty, 9-6 
Entry point, 

abort, 7-14, 7-15 

interrupt, 7-13, 7-15 
$ENTRY table, 3-64 
ENTRY$ p-sect, 2-14 
EOF detection for cassette, 

10-28 
ERL$G, 7-5, 7-34 
ERL$U, 7-34 
Error byte, 

user, 2-4 

user (table) , 2-6 



Error codes, 

EMT, 2-4 

multi-terminal programmed 
requests, 5-24 

XM programmed requests, 4-65 
Error level, 2-5 
Error log file formats, 8-37 
Error logger, 

adding a device to, 7-37 

calling, 7-36 
Error logging, 3-35, 

See Also Logging an error. 

implementing, 7-34 
Error logging example, 7-37 
Error logging subsystem (figure), 

8-38 
Error reporting, 2-5 

hardware magtape handler, 10-13 
Error status, 2-5 

Errors, 

interrupt service routine 

mapping, 6-22 
interrupt service routine 

mapping (figure) , 6-22 
logging, 7-35, 

See Also Error logging, 
memory parity, 4-69 
retry count, 7-12 
retrying at fork level, 7-16 
Errors on data transfer, 7-15 
Examine keyboard command, 2-16 
Example application program, 

C-1 
Example code, 

non-interrupt programmed I/O, 
6-2 
Example device handler, 
DX, A-19 
PC, A-38 
RK, A-1 
Example foreground program, 

C-1 
Example in-line interrupt service 

routine, C-1 
Example of .WDBBK macro, 4-58 
Example of a directory segment 

(figure) , 9-9 
Example program, 

multi-terminal, 5-29 
QUEUE, 3-45 
XM, 4-70 
Examples, 

device time-out, 7-32 
error logging, 7-37 
magtape directory, 10-10 
Examples of SET options, 7-25 
EXIT$, 3-30 
Exiting from interrupt service, 

6-18 
EXPAND, 1-2 
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Extended Inst 

See EIS. 
Extended memo 
Extended memo 
Extended memo 
Extended memo 
Extended memo 
Extended memo 

program. 
Extended memo 
Extended memo 

requests, 
Extended memo 

4-37 
Extension con 

3-54 
Extension con 

(table) , 
Extra directo 



FB, 



ruction Set, 

ry, 4-1 

ry arrays, 4-35 

ry buffers, 4-35 

ry feature, 4-1 

ry hardware, 4-4 

ry multi-user 

4-36 

ry overlays, 4-34 

ry programmed 

4-61 
ry workspace, 

figuration word, 

figuration word 

3-54 

ry words, 9-7 



keeping the USR resident in, 
2-35 
FB monitor impure area, 3-55 
FB system (figure), 2-26 
FB systems, 

scheduling in, 3-23 
File, 

empty. See Empty entry. 

permanent, 9-fi 

tentative, 9-6 
File block, 

QUEUE, 3-43 
File formats, 8-1 

•LDA, 8-28 

•OBJ, 8-1 

.REL, 8-32 

•SAV, 8-30 

.STB, 8-24 

ASCII, 8-34 

CREF, 8-35 

error log, 8-37 

library, 8-25 
File protection, 9-8 
File storage, 9-1 
File storage on random-access 

devices, 9-8 
File structure magtape handler, 

10-2 
File type, 

system job, 3-36 
File-structured devices, 9-1 
Files, 

number of, 9-12 

size of, 9-12 
Fill characters, 2-4 
Fill count, 2-4 
FILST$, 7-8 



Fixed offsets, 

RMON, 3-47 

RMON (table) , 3-48 
Flow of events in I/O processing, 

3-19 
Flowcharting, 6-10, 7-2 
FMS-11, 5-10 

Foreground impure area, 2-27 
Foreground job, 

privileged, 4-31, 4-43 

privileged (figure) , 4-32 

virtual, 4-27, 4-46 

virtual (figure), 4-30 
Foreground job (figure), 2-21 
Foreground job restrictions, 3-35 
Foreground jobs, 2-20 

communicating with, 3-8 

starting, 2-24 

USR swapping considerations 
for, 2-37 
Foreground program example, C-1 
Foreground stack, 2-26 
Foreground/background, See FB. 
Fork block, 6-16 
Fork level, 6-15 
Fork level for retries, 7-16 
.FORK macro summary (table), 6-17 
.FORK macro summary, 6-17 
.FORK macro, 6-15 
Fork queue, 3-9, 6-15 
Fork queue element (figure) , 3-61 
Format , 

DECtape II, 10-40 
Format of IBM floppy (table), 

9-20 
Format of interchange diskette 

(table) , 9-20 
Format of object modules 

(figure) , 8-5 
Format of RT-11 files, 8-1 
Formatted binary blocks, 8-4 
FORTRAN IV, 

interrupts in, 6-18 
FORTRAN program, 

USR swapping and, 2-32 
FORTRAN program in memory 

(figure), 2-34 
FORTRAN program p-sects (table) , 

2-33 
FORTRAN programs, 

p-sect ordering for, 2-33 
FPU traps, 4-68 
Free memory list, 

XM, 4-60 
Free queue elements, 3-13 
Free space, 

managing, 2-19 
FRUN keyboard command, 2-22, 3-39 

FRUN keyboard command (figure) , 
2-25 
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Gaps in virtual address space, 

4-41 
Gaps in virtual address space 

(figure) , 4-42 
GET keyboard command, 2-14 
$GETBYT monitor routine, 7-45 
Getting a character, 5-22 
Getting system status, 5-23 
•GMCX programmed request, 4-63 
GT device handler, 2-19 
•GTLIN programmed request, 

non-terminating, 2-7 
.GVAL programmed request, 3-47 

H 

Handlers, See Device handlers. 
Hard copy terminal, 5-6 
Hard errors, 

logging, 7-35 
Hardware, 

extended memory, 4-4 

multi-terminal, 5-2 
Hardware concepts, 

XM, 4-7 
Hardware console interface, 5-4 
Hardware magtape handler, 10-13 
Hardware magtape handler calls 
with the file structure 
module, 10-12 
Header section, 7-9 
High limit, 

program, 4-38 

virtual, 4-38 
High memory address, 2-4 
High-speed ring buffer, 3-5 
History of RT-11 , 1-1 
HNDLR$, 7-7 

Holding a handler, 3-21, 3-22 
Home block, 9-1 
Home block (figure), 9-3 
Home block (table), 9-3 
How an interrupt works, 6-3 
How files are stored on magtape, 

9-22 
How programs control mapping, 

4-21 
How to queue files, 3-41 
How to write device handler^, 7-1 
$HSIZE table, 3-64 \ 



I 



I.BLOK (table), 3-59 
I.BLOK word, 3-29, 3-59 



I. STATE (table) , 3-58 

I. STATE word, 3-35, 3-58 

I/O, 

asynchronous, 3-12 

interrupt driven, 6-2 

non-interrupt programmed, 6-1 

non-interrupt programmed 
example, 6-2 

queued system, 3-11 

wait-mode, 3-20 
I/O channel format (figure), 3-62 
I/O completion section, 7-16 
I/O in progress, 

stopping, 6-12 
I/O initiation section, 7-11 
I/O limitations, 

terminal, 3-6 
I/O page, 2-10 
I/O page (figure) , 2-11 
I/O processing, 3-19 
I/O queue, 3-12 

adding an element to the, 3-14 

manipulating the, 3-21 
I/O queue element, 3-12 
I/O queue element (figure), 3-13, 

3-60 
I/O queue element in XM, 4-59 

I/O request, 

completing an, 3-22 

queuing an, 3-20 
I/O time-out, 7-28 
I/O transfer, 

performing an, 3-22 
IAS, 

magtapes from, 10-22 
IBM floppy format (table) , 9-20 
Implementing error logging, 7-34 
Implementing SET options, 7-22 
Impure area, 2-21, 3-23, 3-55 

FB monitor, 3-55 

foreground, 2-27 

SJ monitor, 3-55 
Impure area (table), 3-56 
In-line interrupt service 
routine, 6-4 

advantages of, 6-6 

example of, C-1 
Indirect command files, 2-7 

KMON, 2-37 
Information about devices, 6-8 
Information saved during a 

context switch, 3-29 
Inhibiting directory caching, 2-29 
Initial register contents for a 

virtual job (table) , 4-20 
Initial value of stack pointer, 

2-3 
Input ring buffer, 3-3 
Input ring buffer (figure), 3-4, 
3-5 
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Input/output operations, 
completion routines, 3-11, 

3-17, 3-23 
multi-terminal programmed 
requests, 5-20 
INSTALL keyboard command, 7-59 
Installation restrictions, 

overriding, 7-65 
Installation verification 

routine, 7-62 
Installing a device handler, 7-58 
Installing magtape handlers, 7-65 

Instruction, 
BPT, 4-68 

lOT, 4-68 
RTS PC, 6-18 
TRAP, 4-68 
INTACT, 3-33 
$INTEN (table) , 3-26 
$INTEN and the job's stack, 3-26 
.INTEN macro summary (table), 

6-17 
.INTEN macro summary, 6-17 
.INTEN macro, 3-27, 6-13 
SiNTEN monitor routine, 3-25 
Interchange diskette format 

(table) , 9-20 
Interface, 

DLll-J, 5-28 

DLll-W, 5-28 

hardware console, 5-4 
Interleaving, 6-9 
Internal descriptions of I/O 

processing, 3-19 
Internal queuing, 7-20 
Interrupt, 

how it works, 6-3 
Interrupt entry points, 7-13, 

7-15 
Interrupt level counter, 3-25 
Interrupt level counter (table) , 

3-25 
Interrupt levels (figure) , 3-26 
Interrupt service, 

exiting from, 6-18 

local terminal, 5-26 

multi-terminal, 5-25 

remote terminal, 5-26 
Interrupt service routine, 

in-line, 6-4 

planning, 6-8 
Interrupt service routines, 

advantages of in-line, 6-6 

how to write, 6-1 

in XM, 6-20 

mapping error, 6-22 

mapping error (figure) , 6-22 

programmed requests and, 6-14 

registers available in, 6-18 

skeleton outline, 6-19 



Interrupt service routines, (Cont. ) 

structure of, 6-11 
Interrupt service section, 7-13 

writing, 7-15 
Interrupt vector area (figure) , 

2-10 
Interrupt vectors, 2-8, 6-3 

setting up, 6-12 
Interrupt vectors (table) , 2-8 
Interrupt-driven I/O, 6-2 
Interrupts in FORTRAN IV, 6-18 
INTLVL, 3-25 
INTLVL (table), 3-25 
Introduction to multi-terminal 

programmed requests, 5-10 
Introduction to XM programmed 

requests, 4-49 
INTSET system subroutine, 6-18 
lOT instruction, 4-68 
Issuing an I/O request, 3-19 



Job, 

background, 2- 
background (f 
foreground, 2 
privileged, 4 
system, 2-20, 
virtual, 2-7, 
Job block, 

QUEUE, 3-42 
Job blocking bi 
Job blocking bi 
Job names, 

logical, 3-36 
Job number, 3-3 
Job priority, 3 
assigning, 3- 
Job state word, 
Job state word 
Job Status Word 
Job's context. 
Job's start add 
Jobs, 

blocking, 3-3 
differences b 
and backgro 
unblocking, 3 
using a separ 
5-10 
JSW, 2-4, 2-6 
JSW (figure) , 2 
JSW (table) , 2- 
JSW summary, 2 



-14, 2-17 

igure) , 2-15 

-20 

-27, 4-42 

3-35 

2-17, 4-26, 4-44 



ts, 3-59 

ts (table) , 3-59 
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28K-word system memory 

limitations, 4-2 
K-words, 4-2 
K52, 1-3 
KED, 1-3 
Keeping the USR resident in SJ , 

2-30 
Kernel mapping, 4-18, 6-21 
Kernel processor mode, 4-16 
Keyboard command. 

Deposit, 2-16 

Examine, 2-16 

FRUN, 2-22, 3-40 

FRUN (figure) , 2-25 

GET, 2-14 

INSTALL, 7-59 

LOAD, 3-40 

R, 2-16 

R (flowchart) , 2-18 

RESTART, 2-16 

RESUME, 3-40 

RUN, 2-14 

RUN (flowchart), 2-17 

SET TT, 3-40 

SHOW JOBS, 3-40 

SRUN, 2-22, 3-40 

START, 2-14 

SUSPEND, 3-40 

UNLOAD, 3-40 
Keyboard command expansion, 2-37 
Keyboard commands. 

See Also DIGITAL Command 
Language. 

changing, 2-38 
Keyboard commands and system 

jobs, 3-39 
Keyboard Monitor, See KMON. 
KMON, 2-37 

modifying, 2-38 

size of, 2-39 
KMON (figure) , 2-38 
KMON command expansion, 2-37 
KMON indirect file, 2-37 
KMON overlays, 2-37 
KMON sliding, 2-19, 2-37 
KSPND$, 3-30 
KTll, 4-7 



LDA file format, 8-28 
Length of terminal line, 3-6 
Library file format, 8-25 
.LIMIT MACRO-11 directive, 

XM, 4-41 
Limitations, 

32K-word addressing, 4-4 

overcoming memory, 4-2 

terminal I/O, 3-6 



Line, 3-4 

printing, 5-22 
Line length, 3-6 
Link maps, 2-13 
Link words, 

directory, 9-15 
Linker , 

writing a, 8-2 
Linking a device handler, 

7-58 
LOAD keyboard command, 

3-39 
Loading a background job, 2-15 
Loading a device handler, 2-19, 

2-22 
Loading device handlers, 2-19, 

2-22 
Local terminal interrupt service, 

5-26 
Logging a hard error, 7-35 
Logging a soft error, 7-35 
Logging an error, 7-35, 

See Also Error logging. 
Logical address space, 4-25 
Logical job names, 3-36 
Logical unit number. See LUN. 
Low memory, 4-1 
Low-memory bitmap, 2-1, 3-52 
Low-memory bitmap (table), 

3-53 
Lowering processor priority, 

6-13, 7-14 
LS handler, 5-6 
LUN, 5-1 
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MAC library file format, 8-25 
Macro, 

.CTIMIO, 7-30 

.DEVICE, 6-12 

.FORK, 6-15 

.INTEN, 3-27, 6-13 

.PROTECT, 6-11 

.RDBBK, 4-53 

.RDBDF, 4-52 

.SYNCH, 3-19, 6-14, 
See Also Synch. 

.TIMIO, 7-28 

.WDBBK, 4-57 

.WDBBK example, 4-58 

•WDBDF, 4-56 

DEV, 7-60 

ELBLDR, 7-37 
Macro calls summary, 6-17 
Macro calls summary (table), 6-17 
MACRO program, 

USR swapping and, 2-31 
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MACRO-11 directive, 

.MCALL, 7-4 

XM .LIMIT, 4-41 
Magnetic tape. See Magtape. 
Magtape, 

bootable, 9-23 

how files are stored on, 9-22 

reading physical blocks, 10-14 

rewinding, 10-18 

seven-track, 10-22 

spacing backward, 10-15 

spacing forward, 10-15 

writing physical blocks, 10-14 

writing with extended gap, 
10-18 
Magtape directory example, 10-10 
Magtape handler, 7-65 

error reporting, 10-13 

file structure, 10-2 

hardware, 10-13 

hardware calls with the file 
structure module, 10-12 

writing, 7-40 
Magtape handler specifics, 10-1 
Magtape labels, 

ANSI (table) , 9-23 
Magtape programmed requests, 

10-4 
Magtape structure, 9-22 
Magtape tape mark, 

writing, 10-18 
Magtapes from IAS, 10-22 
Magtapes from RSTS/E, 10-21 
Magtapes from RSX-llD, 10-22 
Magtapes from RSX-llM, 10-21 
Managing free space, 2-19 
•MAP programmed request, 4-62 

Mapping, 4-7, 4-26 

default, 4-18 

default (figure) , 4-19 

how programs control, 4-21 

kernel, 4-18, 6-21 

PARI, 7-47 

privileged, 4-26, 6-21 

selecting virtual, 4-26 

user, 4-18 

virtual, 4-26 
Mapping a window to a region, 

4-62 
Mapping errors, 

interrupt service routine, 6-22 

interrupt service routine 
(figure) , 6-22 
Mapping status, 

obtaining, 4-63 
Maps, 

link, 2-13 
.MCALL MACRO-11 directive, 7-4 



Memory, 

extended, 4-1 

low, 4-1 
Memory allocation, 2-19, 2-21 
Memory layout, 

XM, 4-20 

XM (figure), 4-21 
Memory layouts, 2-1 
Memory limitations. 




3-38 
MINC-11, 5-3 
MM handler specifics, 10-1 
MMG$T, 7-5 

MMU , See Memory management unit. 
Modem, 5-26 

BELL 103A-type, 5-28 
Modifying keyboard commands, 2-38 
Modifying KMON, 2-38 
Monitor , 

Resident, See RMON. 

XM, See XM monitor. 
Monitor device tables, 3-62 

adding a device to, 3-65 
Monitor files, 7-50 
Monitor p-sects, 2-13 
Monitor p-sects (table) , 2-13 
Monitor routine, 

$ENSYS, 3-27 

$GETByT, 7-45 

$INTEN, 3-25 

$MPPHY, 7-44 

$PUTByT, 7-45 

$PUTWRD, 7-46 

$RQTSW, 3-33 

$SYSWT, 3-31 

$SYSWT (flowchart), 3-32 

XM, 7-44 
Moving the console, 5-4 
$MPPHY monitor routine, 7-44 
MQ handler, 3-39, 6-22 

MQ handler restrictions, 3-39 

MS handler specifics, 10-1 

MT handler specifics, 10-1 

.MTATCH programmed request, 5-20 

.MTDTCH programmed request, 5-23 

MTEMT$ p-sect, 2-14 

.MTGET programmed request, 5-21 

.MTIN programmed request, 5-22 

MTINT$ p-sect, 2-14 

.MTOUT programmed request, 5-22 

.MTPRNT programmed request, 5-22 
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.MTRCTO programmed request, 5-23 

•MTSET programmed request, 5-21 

•MTSTAT programmed request, 5-23 

MTTEMT.MAC, 5-1 

MTTINT.MAC, 5-1 

MTTV?$ p-sect, 2-14 

MTYSET.MAC, 5-29 

MU BASIC-11, 3-35, 5-10 

Multi-tasking, 3-35 

Multi-terminal activities 

summary, 5-10 
Multi-terminal activities summary 

(table) , 5-10 
Multi-terminal application, 

debugging, 5-29 
Multi-terminal applications, 5-10 
Multi-terminal data structures, 

5-1, 5-11 
Multi-terminal example program, 

5-29 
Multi-terminal feature, 5-1 
Multi-terminal hardware, 5-2 
Multi-terminal interrupt service, 

5-25 
Multi-terminal polling routines, 

5-27 
Multi-terminal programmed request 

error codes, 5-24 
Multi-terminal programmed 

requests, 5-20 
introduction to, 5-10 
Multi-terminal restrictions, 5-28 
Multi-terminal system components, 

5-1 
Multi-user program in extended 

memory, 4-36 
Multi-vector device handler, 7-10 
Multiplexer, 5-2 
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OBJ file format, 8-1 
OBJ library file format, 8-25 
Object file format, 8-1 
Object module format (figure), 

8-5 
Obtaining a character, 5-22 
Obtaining mapping status, 4-63 
Obtaining system status, 5-23 
Obtaining terminal status, 5-21 
Obtaining the current cursor 

position, 3-8 
Obtaining the SET options status 

word, 3-8 
ODT, 

using in XM, 7-68 

using to debug device handlers, 
7-66 
Offsets, 

queue element, 7-5 

RMON fixed, 3-47 

RMON fixed (table) , 3-48 
Optimizing USR operations, 2-36 
OS-11, 1-1 
OS/8, 1-1 

Output ring buffer, 3-2 
Output ring buffer (figure), 3-2, 

3-3 
Overlaid programs, 2-25 
Overlaying (figure), 4-4 
Overlays, 

extended memory, 4-34 

KMON, 2-37 

REL files with, 8-34 
Overriding installation 

restrictions, 7-65 
OVLY p-sect, 2-14 
$OWNER table (figure) , 3-65 
$OWNER table, 3-65 
OWNER$ p-sect, 2-13 



Next free address, 4-38 
NL device handler, 10-39 
Non-file-structured .LOOKUP 

programmed request, 10-19 
Non-file-structured .READ 

programmed request, 10-20 

Non-file-structured .WRITE 

programmed request, 10-20 

Non-interrupt programmed I/O, 6-1 
example, 6-2 

NonXM .SETTOP programmed request, 
4-40 

NORUN$, 3-30 

Null handler, 10-39 

Number of files, 9-12 



P-sect ordering for FORTRAN 

programs, 2-33 
P-sects, 8-5 

FORTRAN program (table), 2-33 

monitor, 2-13 

monitor (table) , 2-13 
Page Address Register, See PAR. 
Page Descriptor Register, 

See PDR. 
Pages, 

virtual address, 4-9 

virtual address (figure) , 4-10 
Paper tape device handler, 10-34 
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PAR, 4-13 

PARI mapping, 7-47 

PARI restriction, 4-66, 6-22 

PAR2 restriction, 4-67 

PATCH$ p-sect, 2-14 

Patching a TCB, 5-18 

PATCHO, 1-2 

PC device handler, 10-34 

PC device handler listing, A-38 

PDR, 4-13 

PDT-11, 5-3, 5-27 

Performing an I/O transfer, 3-22 

Permanent file, 9-6 

Physical address, 4-2 

Physical address region, 4-22, 

See Also Region. 
Physical unit number. See PUN. 
PIC, 6-13, 7-2, 7-11 
PIPC, 1-2 

Planning a device handler, 7-1 
Planning an interrupt service 

routine, 6-8 
Planning XM applications, 4-49 
PLAS, 4-25 
$PNAME table, 3-62 
PNAME$ p-sect, 2-14 
Polling routine for DZ interface, 

5-27 
Polling routines, 5-27 
Position-Independent Code, 

See PIC. 
PP device handler, 1-2 
PR device handler, 1-2 
Preamble section, 7-3 
Primary driver, 7-51 
Printer, 

using a terminal as, 5-6 
Printing a line, 5-22 
Printing characters, 5-22 
Priority, 

assigning job, 3-37 
device, 6-3 
job, 3-36 

lowering, 6-13, 7-14 
processor, 6-3 
Priority structure, 6-3 
Priority structure (figure), 6-3 
Private console, 5-5 
Privileged background job, 4-31, 

4-43 
Privileged background job 

(figure) , 4-31 
Privileged foreground job, 4-31, 

4-43 
Privileged foreground job 

(figure) , 4-32 
Privileged jobs, 4-27, 4-42 
differences between virtual 
jobs and, 4-32 
Privileged mapping, 4-26, 6-21 



Privileged system job, 4-31 
Privileged system job (figure), 

4-32 
Processor mode, 

kernel, 4-16 

user, 4-16 
Processor priority, 6-3 
Processor Status word, See PS. 
Program, 

how to queue files from, 3-41 
Program control of mapping, 

4-21 
Program high limit, 4-38 
Program sections, See P-sects. 
Program status, 2-5 
Programmed request, 

.CHAIN, 2-16 

.CRAW, 4-61 

.CRRG, 4-61 

•ELAW, 4-64 

.ELRG, 4-64 

.GMCX, 4-63 

.GTLIN (non-terminating) , 2-7 

.GVAL, 3-47 

.MAP, 4-62 

.MTATCH, 5-20 

.MTDTCH, 5-23 

.MTGET, 5-21 

.MTIN, 5-22 

.MTOUT, 5-22 

.MTPRNT, 5-22 

•MTRCTO, 5-23 

.MTSET, 5-21 

.MTSTAT, 5-23 

.SETTOP in XM, 4-38, 4-41, 4-43 

-SETTOP nonXM, 4-40 

.SPFUN, 7-38 

.UNMAP, 4-63 

non-file-structured .LOOKUP, 
10-19 

non-file-structured .READ, 
10-20 

non-file-structured .WRITE, 
10-20 
Programmed request error codes, 

multi-terminal, 5-24 

XM, 4-65 
Programmed request restrictions 

in XM, 4-67 
Programmed requests, 

introduction to multi-terminal, 
5-10 

introduction to XM, 4-49 

magtape, 10-4 

multi-terminal, 5-20 

XM, 4-61 
Programmed requests and system 
jobs, 3-38 

Programmed requests in interrupt 
service routines, 6-14 
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Programming for specific devices, 
10-1 

•PROTECT macro, 6-11 

Protected files, 9-8 

Protected locations, 3-53 

Protecting vectors, 6-11 

Protection, 

low-memory bitmap, 3-52 
low-memory bitmap (table) , 3-53 

PS, 2-10, 4-17, 6-4 

PS (figure) , 6-5 

PS condition codes, 7-11 

Pseudo clock, 3-11 

Pseudo devices, 7-19 

PUN, 5-2 

$PUTBYT monitor routine, 7-45 

$PUTWRD monitor routine, 7-46 



Queue, 

adding an 

3-14 

completion 

fork, 3-9, 

I/O, 3-12 

timer, 3-1 

QUEUE, 3-35, 

QUEUE acknow 

Queue elemen 

completion 

completion 

fork, 6-16 

fork (figu 

I/O, 3-12 

I/O (figur 

I/O in XM, 

synch, 3-1 

synch (fig 

timer, 3-1 

timer (fig 

Queue elemen 

Queue elemen 

Queue elemen 

Queue elemen 

allocating 

available 

free, 3-13 

QUEUE exampl 

QUEUE file b 

QUEUE job bl 

QUEUE reques 

Queued I/O s 

Queued I/O s 

3-11 
Queued I/O s 
(figure) 
Queuing , 
internal , 



element to the I/O, 

, 3-17 

6-15 



3-41 
ledgment block, 3-45 
t, 
, 3-18 

(figure) , 3-18, 3-60 

re) , 3-61 

e) , 3-13, 3-60 

4-59 
9, 6-15 

ure) , 3-19, 3-61 


ure) , 3-10, 3-62 
t in XM, 7-42 
t offsets, 7-5 
t summary, 3-59 
ts, 

, 3-12 
( figure) , 3-14 

e program, 3-45 
lock, 3-43 
ock, 3-42 
t block, 3-44 
ystem, 3-11 
ystem components, 

ystem components 
, 3-12 

7-20 



Queuing an I/O request, 3-20 
Queuing files, 3-35 
Queuing files from a program, 
3-41 



R keyboard command, 2-16 

R keyboard command (flowchart), 

2-18 
Race conditions, 6-10 
Random-access device (figure) , 

9-2 
Random-access devices, 9-1 

file storage, 9-8 
•RDBBK macro, 4-53 
.RDBDF macro, 4-52 
Read pass-all mode, 5-18 
Reading physical blocks on 

magtape, 10-14 
Recovering data from a device, 

9-15 
Region, 4-22, 

See Also Physical address 

region, 
creating, 4-61 
eliminating, 4-64 
mapping a window to, 4-62 
physical address, 4-22 
Region control block, 4-22, 4-53 
Region control block (figure), 

4-53 
Region control block (table), 

4-54 
Region definition block, 4-22, 

4-51 
Region definition block (figure), 

4-51 
Region definition block (table), 

4-52 
Region status word, 4-51 
Region status word (table), 4-52 
Regions, 

dynamic, 4-24 
static, 4-23 
Registers available in interrupt 

service routines, 6-18 
REL file format, 8-32 
REL files with overlays, 8-34 
REL files without overlays, 8-32 
Relationship between RMON and a 

device handler, 3-22 
Relocatable file format, 8-32 
Relocation, 

virtual address, 4-9 
Remote terminal interrupt 

service, 5-26 
Removing data from a corrupted 

device, 9-15 
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Replacement bad blocks, 7-40 
Request block, 

QUEUE, 3-44 
Requesting a scheduling pass, 

3-32 
Resetting CTRL/0, 5-23 
Resident Monitor, See RMON . 
RESTART keyboard command, 2-16 
Restarting terminal output, 3-7 
Restriction, 

MQ handler, 3-39 

PARI, 3-39, 4-66, 6-22 

PAR2, 3-39, 4-67 

system job, 3-39 

XM, 4-66 
Restrictions, 

.SYNCH in XM, 6-23 

foreground job, 3-35 

multi-terminal, 5-28 

system job, 3-35 
Restrictions for interrupt 

service routines in XM, 6-20 
Restrictions for programmed 

requests in XM, 4-67 
RESUME keyboard command, 3-40 
Retry count for errors, 7-12 
Retrying errors at fork level, 

7-16 
Rewinding magtape, 10-18 
Ring buffer, 3-1 

high-speed, 3-5 

input, 3-3 

input (figure), 3-4, 3-5 

output, 3-2 

output (figure), 3-2, 3-3 
RK device handler listing, A-1 
RK06/07 device handler, 10-35 
RLOl/02 device handler, 10-37 
RMNUSR p-sect, 2-13 
RMON, 2-12, 3-1, 3-22 

size of, 2-39 

start of, 2-4 
RMON fixed offsets (table), 3-48 
RMON (figure) , 2-12 
RMON data structures, 3-47 
RMON fixed offsets, 3- *7 
RMON p-sect, 2-14 
RONLY$, 7-8 
Routine, 

completion, 3-11, 3-17, 3-23 
Routines, 

how to write interrupt service, 
6-1 

in-line interrupt service, 6-4 

multi-terminal polling, 5-27 

structure of interrupt service, 
6-11 
$RQTSW monitor routine, 3-33 
RSTS/E, 

magtapes from, 10-21 



RSX-llD, 

magtapes from, 10-22 
RSX-llM, 

magtapes from, 10-21 
RT-11, 

history of, 1-1 

version 1, 1-1 

version 2, 1-2 

version 3, 1-2 

version 4, 1-3 
RT-11 data blocks, 8-4 
RT-11 file formats, 8-1 
RTll p-sect, 2-13 
RTBL.MAP, 2-13 
RTDATA p-sect, 2-13, 3-47 
RTFB.MAP, 2-13 
RTPS-11, 1-2 

RTS PC instruction, 6-18 
RTSJ.MAP, 2-13 
RUN keyboard command, 2-14 
RUN keyboard command (flowchart), 

2-17 
Runnable job, 

characteristics of, 3-33 
Running a job twice, 2-25 



Sample application program, C-1 

SAV file format, 8-30 

Save image file format, 8-30 

Scheduler, 3-23 

Scheduler and completion 

routines, 3-33 
Scheduler operations, 3-32 
Scheduling considerations for 

system jobs, 3-37 
Scheduling in FB systems, 3-23 
Scheduling pass, 3-20, 3-32 
Second terminal configuration 

word, 5-17 
Selecting virtual mapping, 4-26 
Sequential-access devices, 9-1, 

9-22 
Serial line unit. See SLU. 
SET command execution, 7-23 
SET option examples, 7-25 
SET options status word, 3-8 
SET options, 

implementing, 7-22 
SET options status word (table), 

3-8 
SET table format, 7-23 
SET TT keyboard command, 3-40 
Setting terminal characteristics, 

5-21 
Setting the user error byte, 2-6 
Setting up the interrupt vector, 

6-12 
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.SETTOP programmed request, 
nonXM, 4-40 
XM, 4-38, 4-41, 4-43 
.SETTOP summary (table), 4-47, 

4-49 
.SETTOP summary, 4-46 
Seven-track magtape, 10-22 
Severe status, 2-5 
Shared console, 5-5 
Sharing the USR, 2-37 
SHOW JOBS keyboard command, 3-40 
Silo, 

diskette, 6-2 
Size of device handlers, 2-39 
Size of files,, 9-12 
Size of KMON, 2-39 
Size of RMON, 2-39 
Size of USR, 2-39 
Sizes of components, 2-38 

determining, 2-39 
Sizes of distributed components 

(table) , 2-38 
SJ, 

keeping the USR resident in, 
2-30 
SJ completion routines, 3-18 
SJ considerations for the 

completion queue, 3-18 
SJ monitor impure area, 3-55 
SJ systems without timer service, 

3-9 
Skeleton outline of a device 

handler, 7-19 
Skeleton outline of an interrupt 

service routine, 6-19 
Sliding , 

KMON/USR, 2-19 
SLU, 5-3 
Soft errors, 

logging, 7-35 
Software bootstrap, 

writing, 7-52 
Software concepts, 

XM, 4-20 
Space considerations for system 

jobs, 3-38 
Spacing backward on magtape, 

10-15 
Spacing forward on magtape, 10-15 
Special directories, 7-40 
Special functions, 7-38 
cassette, 10-27 
DM handler, 10-36 

Special mode, 3-4 
SPECL$, 7-8 

.SPFUN programmed request, 7-38 
SPFUN$, 7-7 

Splitting a directory segment, 
9-13 



Splitting a directory segment 

(figure), 9-16 
SPND$, 3-30 

SHUN keyboard command, 2-22, 3-39 
Stack, 

foreground, 2-26 
Stack after $ENSYS, 3-27 
Stack after $INTEN, 3-26 
Stack pointer, 

initial value, 2-3 
STACK$ p-sect, 2-14 
Start address of job, 2-3 
START keyboard command, 2-14 
Start of RMON, 2-4 
Starting a data transfer, 7-12 
Starting foreground jobs, 2-24 
Starting system jobs, 2-24 
$STAT table, 3-63 
STAT$ p-sect, 2-14 
Static region, 4-23 
Static window, 4-24 
Status registers, 

XM, 4-16 
Status word, 

SET options, 3-8 
SET options (table) , 3-8 
STB file format, 8-24 
Stopping in-progress I/O 

transfers, 6-12 
Storing files, 9-1 
Storing time of day, 3-10 
Stream ASCII file format, 8-34 
Structure of a device handler, 

7-3 
Structure of cassette, 9-24 
Structure of interrupt service 

routines, 6-11 
Structure of magtape, 9-22 
Structure of the USR, 2-27 
Success status, 2-5 
Suffix, 

device handler, 3-51 
Summary of .SETTOP action, 4-46 
Summary of .SETTOP action 

(table) , 4-47, 4-49 
Summary of macro calls, 6-17 
Summary of macro calls (table) , 

6-17 
Summary of multi-terminal 

activities, 5-10 
Summary of multi-terminal 

activities (table), 5-10 
Summary of queue elements, 

3-59 
Summary of XM activities, 4-50 
Summary of XM activities (table) , 

4-50 
SUSPEND keyboard command, 3-40 
Suspending terminal output, 3-7 
SWAP. SYS, 2-16 
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Swapping, 

USR considerations, 2-30 
Switching terminals, 5-5 
Switching the console terminal, 

5-8 
Switching to system state 
asynchronously, 3-25 

Switching to system state 

synchronously, 3-27 
Switching to user state, 3-28 
SYCND, 7-58 
Symbol table definition file 

format, 8-24 
Synch, See Also .SYNCH macro. 
Synch block, 6-15 
.SYNCH considerations for the 

completion queue, 3-18 
.SYNCH macro in XM, 6-23 
.SYNCH macro summary (table), 

6-17 
•SYNCH macro summary, 6-17 
.SYNCH macro, 6-14, 

See Also Synch. 
Synch queue element, 3-19 
Synch queue element (figure), 

3-19, 3-61 
Synchronous system trap vectors, 

4-67 
Synchronous system trap vectors 

(table) , 4-67 
Synchronous system traps in XM, 

4-67 
SYSCOM, 

See System communication 

area. 
SYSGEN (table), 3-55 
SYSGEN word, 3-54 
SYSTBL.MAC, 5-1 

System communication area, 2-3 
System communication area 

(figure) , 2-3 
System communication area 

(table) , 2-3 
System components, 2-1 
System device handler, 2-11, 7-50 
System device handler (figure) , 

2-12 
System generation conditionals, 

7-4 
System generation features word, 

3-54 
System generation features word 

(table) , 3-55 
System job, 

virtual, 4-27, 4-46 
virtual (figure) , 4-30 
System jobs, 2-20, 3-35 
characteristics of, 3-36 
communicating with, 3-8, 3-40 
design considerations for, 3-37 
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T.CNF2 word, 5-17 
T.CNFG word, 5-15 
T.STAT word, 5-18 
Tables, 

adding a device to, 3-65 

monitor device, 3-62 
Tape mark, 

writing, 10-18 
TCB, 5-1, 5-11 

patching, 5-18 
TCB contents (table), 5-13 
TCB format (figure), 5-12 
TECO, 1-2 

Tentative file, 9-6 
Terminal , 

attaching, 5-20 

console, 5-4 

detaching, 5-23 

hard copy, 5-6 

local, 5-26 

remote, 5-26 

video, 5-6 
Terminal characteristics, 

setting, 5-21 
Terminal configuration, 5-3 
Terminal configuration word, 5-15 

second, 5-17 
Terminal control block. See TCB. 
Terminal I/O limitations, 3-6 
Terminal line length, 3-6 
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Terminal output, 
discarding, 3-7 
restarting, 3-7 
suspending, 3-7 
Terminal service, 3-1 
Terminal special mode, 3-4 
Terminal status, 

obtaining, 5-21 
Terminal status word, 5-18 
Terminals, 

switching, 5-5 
Termination section, 7-18 
Testing a device handler, 7-65 
Text editor, 
K52, 1-3 
KED, 1-3 
TECO, 1-2 
TIM$IT, 7-5 
Time of day, 3-9 

storing, 3-10 
Time-out example, 

line printer, 7-32 
Time-out routine for DL 

interface, 5-27 
Time-out support, 7-28 
Timer block format, 7-29 
Timer queue, 3-10 
Timer queue element, 3-10 
Timer queue element (figure), 

3-10, 3-62 
Timer service, 3-9 

SJ systems without, 3-9 
systems with, 3-9 
•TIMIO macro, 7-28 
Transparency, 3-4, 5-18 
TRAP instruction, 4-68 
Trap to 10, 4-68 
Trap to 4, 4-68 
Trap vectors, 2-1 

synchronous system (table), 

4-67 
synchronous system trap, 4-67 
Trap vectors (figure), 2-2 
Trap vectors (table), 2-2 
Traps, 

FPU, 4-68 

synchronous system in XM, 4-67 
to 4 and 10, 4-68 
TT device handler, 3-1, 10-34 
TTCNFG , 3-8 
TTIWT$, 3-30 
TTOEM$, 3-30 
TTOWT$, 3-30 
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$UNAM1 table, 3-64 
UNAM1$ p-sect, 2-13 
$UNAM2 table, 3-64 



UNAM2$ p-sect, 2-14 
Unblocking a job, 3-32 
Unconditionally fatal status, 2-5 
UNLOAD keyboard command, 3-39 
■UNMAP programmed request, 4-63 
Unmapping a window, 4-63 
User error byte, 2-4 

setting, 2-6 
User error byte (table) , 2-6 
User mapping, 4-18 
User processor mode, 4-16 
User program error code. 
See User error byte. 
User Service Routine, See USR. 
User state, 3-20, 3-24 

switching to, 3-28 
User state (figure), 3-26 
Using a separate terminal for 

each job, 5-10 
Using a terminal as a printer, 

5-6 
USR, 2-27 

keeping resident in FB , 2-35 
keeping resident in SJ , 2-30 
new directory segments and, 

2-29 
optimizing operations, 2-36 
size of, 2-39 
USR (figure) , 2-28 
USR buffer, 2-27 
USR execution, 2-29 
USR load address, 2-4 
USR sharing, 2-37 
USR sliding, 2-19 
USR structure, 2-27 
USR swapping, 2-22 
USR swapping considerations, 2-30 
USR swapping considerations for 

background jobs, 2-36 
USR swapping considerations for 

foreground jobs, 2-37 
USR swapping considerations for 

system jobs, 2-37 
USR swapping with an SJ FORTRAN 

program, 2-32 
USR swapping with an SJ MACRO 

program, 2-31 
USRWT$, 3-30 



Variable-size volumes, 7-40 

VDT debugging program, 4-69, 5-29 

Vector area, 

interrupt (figure) , 2-10 
Vectors, 

interrupt, 2-8, 6-3 

interrupt (table) , 2-8 

protected, 3-53 
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Vectors, (Cont) 

protecting, 3-52, 6-11 
setting up, 6-12 
synchronous system trap, 4-67 
synchronous system trap 

(table) , 4-67 
trap, 2-1 

trap (figure) , 2-2 
trap (table) , 2-2 
Version 1, 1-1 
Version 2, 1-2 
Version 3, 1-2 
Version 4, 1-3 
Video terminal, 5-6 
virtual address, 4-2 
Virtual address pages, 4-9 
Virtual address pages (figure), 

4-10 
Virtual address relocation, 4-9 
Virtual address space gaps, 4-41 
Virtual address space gaps 

(figure) , 4-42 
Virtual address window, 4-24, 

See Also Window. 
Virtual addresses, 

correspondence with APRs 
(table) , 4-56 
Virtual background job, 4-27, 

4-45 
Virtual background job (figure), 

4-28 
Virtual Debugging Technique, 

See VDT. 
Virtual foreground job, 4-27, 

4-46 
Virtual foreground job (figure), 

4-30 
Virtual high limit, 4-38 
Virtual job, 2-7, 2-17, 4-26, 

4-44 
Virtual job initial register 

contents (table), 4-20 
Virtual jobs, 

differences between privileged 
jobs and, 4-32 
Virtual mapping, 4-26 

selecting, 4-26 
Virtual system job, 4-27, 4-46 
Virtual system job (figure), 4-30 
Volumes, 

variable-size, 7-40 
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Wait-mode I/O, 3-20 
Warning status, 2-5 
.WDBBK macro exammple, 4-5f 
.WDBBK macro, 4-57 
.WDBDF macro, 4-56 



Window, 4-24 

See Also Virtual address 
window, 
creating, 4-61 
eliminating, 4-64 
mapping to a region, 4-62 
unmapping, 4-63 
virtual address, 4-24 
Window control block, 4-24, 4-59 
Window control block (figure), 

4-59 
Window control block (table), 

4-60 
Window definition block, 4-24, 

4-53 
Window definition block (figure), 

4-54 
Window definition block (table) , 

4-55 
Window status word, 4-54 
Window status word (table), 4-57 
Windows, 

dynamic, 4-25 
static, 4-24 
WONLY$ , 7-8 
Work space in extended memory, 

4-37 
Write pass-all mode, 5-18 
Writing a tape mark, 10-18 
Writing magtape with extended 

gap, 10-18 
Writing physical blocks on 

magtape, 10-14 
Writing the interrupt service 
section, 7-15 



XM, 

•SYNCH macro in, 6-23 
device handler in (figure), 

7-43 
I/O queue element in, 4-59 
interrupt service routines in, 

6-20 
queue element in, 7-42 
using ODT in, 7-68 
XM .LIMIT MACRO-11 directive, 

4-41 
XM .SETTOP programmed request, 

4-38, 4-41, 4-43 
XM activities summary, 4-50 
XM activities summary (table) , 

4-50 
XM address conversion, 4-9 
XM and synchronous system traps, 

4-67 
XM applications, 4-34 
debugging, 4-69 
planning, 4-49 
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XM context switching, 4-32 

XM data structures, 4-51 

XM design implications, 4-66 

XM device handlers, 7-41 

XM environment, 7-41 

XM example program, 4-70 

XM free memory list, 4-60 

XM hardware concepts, 4-7 

XM memory layout, 4-20 

XM memory layout (figure), 4-21 

XM monitor, 4-7 

XM monitor routines, 7-44 



XM programmed request error 

codes, 4-65 
XM programmed requests, 4-61 

introduction to, 4-49 
XM restrictions, 4-66 
XM restrictions for programmed 

requests, 4-67 

XM software concepts, 4-20 
XM status registers, 4-16 
XMSUBS p-sect, 2-14 
XOFF, 3-7 
XON, 3-7 
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